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

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

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.

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

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

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

View as Markdown