# Reddit

Retrieve subreddit listings, subreddit metadata, a user's post history, a single post, or a comment thread, all in Reddit's own JSON shape.

## Endpoints

```
GET /v1/reddit/subreddit/{subreddit}
GET /v1/reddit/subreddit/{subreddit}/about
GET /v1/reddit/user/{username}
GET /v1/reddit/post/{id}
GET /v1/reddit/comments/{id}
```

## Description

Unlike most other Serply endpoints, Reddit's parameters are ordinary query parameters after a real path segment, not packed into the path itself:

```
https://api.serply.io/v1/reddit/subreddit/python?limit=10&sort=hot
```

Responses are cached for 10 minutes. A cached response does not consume prepaid credits.

## Authentication

All requests require authentication using the `X-Api-Key` header. See the [Authentication guide](/docs/guides/authentication) for more details.

## Path Parameters

### `subreddit` (required for the subreddit endpoints)

**Type:** `string`

A subreddit name, without the `r/` prefix.

**Examples:** `python`, `AskReddit`

### `username` (required for the user endpoint)

**Type:** `string`

A Reddit username, without the `u/` prefix.

**Example:** `spez`

### `id` (required for the post and comments endpoints)

**Type:** `string`

A Reddit post ID (the same ID that appears in the post's URL).

**Example:** `1vfemi1`

## Query Parameters

`subreddit` and `user` accept `limit`, `sort`, `t`, and `after`. `comments` accepts only `sort`. `post` accepts `sort` and `with_comments`. `subreddit/{subreddit}/about` accepts none.

### `limit` (optional)

**Type:** `integer`

How many items to return. Defaults to `25`. Accepts `1` to `100`.

### `sort` (optional)

**Type:** `string`

Sort order. Defaults to `hot` for listings and `confidence` for comment threads.

**Common values:** `hot`, `new`, `top`, `confidence`

### `t` (optional)

**Type:** `string`

Time window, used together with a `top`-style sort. Defaults to `all`.

**Allowed values:** `hour`, `day`, `week`, `month`, `year`, `all`

### `after` (optional)

**Type:** `string`

Pagination cursor. Pass the previous response's `data.after` to fetch the next page.

### `with_comments` (optional, `post` only)

**Type:** `boolean`

Adds the post's comment tree to the response under a `comments` key. Defaults to `false`.

## Request Example

### Using cURL

```bash
curl --request GET \
  --url 'https://api.serply.io/v1/reddit/subreddit/python?limit=10&sort=hot' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

### Using JavaScript/Node.js

```javascript
const response = await fetch(
  'https://api.serply.io/v1/reddit/subreddit/python?limit=10&sort=hot',
  {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY'
    }
  }
);
const data = await response.json();
console.log(data);
```

### Using Python

```python
import requests

response = requests.get(
    'https://api.serply.io/v1/reddit/subreddit/python',
    params={'limit': 10, 'sort': 'hot'},
    headers={'X-Api-Key': 'YOUR_API_KEY'}
)
data = response.json()
print(data)
```

## Response

The response is Reddit's own listing shape, untouched, so anything that already knows how to read a Reddit listing needs no translation layer.

### Response Structure

```json
{
  "kind": "Listing",
  "data": {
    "after": "t3_1vpk70t",
    "children": [
      {
        "kind": "t3",
        "data": {
          "title": "string",
          "subreddit_name_prefixed": "string",
          "selftext": "string",
          "score": "number",
          "num_comments": "number"
        }
      }
    ]
  }
}
```

### Response Fields

- **`kind`** (string): Reddit's type tag for the top-level object, e.g. `Listing`
- **`data`** (object): The listing payload
  - **`after`** (string | null): Pagination cursor for the next page, or `null` on the last page
  - **`children`** (array): The listing items, each Reddit's own `kind`/`data` shape (e.g. `t3` for a post, `t1` for a comment)

`subreddit/{subreddit}/about` returns a single object (not a listing) describing the subreddit itself.

`comments/{id}` is the one endpoint that does not return Reddit's shape at the top level. It returns an envelope, `{ "cached": boolean, "data": [...] }`, where `data` holds two listings: the post first, then its comment tree. Read the thread from `data[1].data.children`, where each child is a `t1` comment.

```json
{
  "cached": true,
  "data": [
    { "kind": "Listing", "data": { "children": [ { "kind": "t3", "data": { "title": "..." } } ] } },
    { "kind": "Listing", "data": { "children": [ { "kind": "t1", "data": { "body": "..." } } ] } }
  ]
}
```

### Reading a single post

`post/{id}` is the same upstream call as `comments/{id}` with the unwrapping done for you: it returns the post object itself — no `Listing` envelope, no array — so the body is at `selftext` rather than `data[0].data.children[0].data.selftext`.

```bash
curl --request GET \
  --url 'https://api.serply.io/v1/reddit/post/1ul97v0' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

```json
{
  "id": "1ul97v0",
  "title": "What should an open-source browser for AI agents actually solve?",
  "subreddit_name_prefixed": "r/AI_Agents",
  "author": "championscalc",
  "selftext": "I'm thinking about starting an open-source project for AI agents...",
  "selftext_html": "<!-- SC_OFF --><div class=\"md\">...",
  "url": "https://www.reddit.com/r/AI_Agents/comments/1ul97v0/...",
  "permalink": "/r/AI_Agents/comments/1ul97v0/what_should_an_opensource_browser_for_ai_agents/",
  "score": 2,
  "num_comments": 18,
  "created_utc": 1782970036.0
}
```

`selftext` is the post body as the author wrote it, in Reddit's markdown; `selftext_html` is the same body pre-rendered. A link post has an empty `selftext` — its content is the `url` it points at. Add `?with_comments=true` to get the comment tree alongside the post, under a `comments` key holding the same `t1` children `comments/{id}` returns.

### Example Response

```json
{
  "kind": "Listing",
  "data": {
    "after": "t3_1vpk70t",
    "children": [
      {
        "kind": "t3",
        "data": {
          "title": "Showcase Thread",
          "subreddit_name_prefixed": "r/Python",
          "selftext": "Post all of your code/projects/showcases here...",
          "score": 42,
          "num_comments": 118
        }
      }
    ]
  }
}
```

## Status Codes

- **200 OK** - Successful response
- **404 Not Found** - No post exists with that ID (`post` endpoint only)
- **429 Too Many Requests** - Rate limit exceeded
- **502 Bad Gateway** - The Reddit proxy is temporarily unavailable

## Error Responses

See the [Errors guide](/docs/guides/errors) for information on error response formats.