# Reddit

Retrieve subreddit listings, subreddit metadata, a user's post history, 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/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 comments endpoint)

**Type:** `string`

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

**Example:** `1vfemi1`

## Query Parameters

`subreddit` and `user` accept all three of the parameters below. `comments` accepts only `sort`. `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.

## 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": "..." } } ] } }
  ]
}
```

### 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
- **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.