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 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

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

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

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

{
  "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.

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

Example Response

{
  "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 for information on error response formats.

View as Markdown