Subreddit Posts API

Subreddit Posts API and subreddit scraper — list a subreddit's hot, new, top, or controversial posts with scores, comment counts, and media as JSON. $0.01 per call.

POST/v1/reddit/subreddit-posts

$0.01/call

The Subreddit Posts API lists posts from any public subreddit, sorted the same way as on Reddit: hot, new, top, or controversial (with a time window for the last two). It's a drop-in replacement for a subreddit scraper — no HTML parsing, no Reddit app registration, and paging is a single cursor field.

Each post includes its permalink, which you can pass to the Reddit Comments API to pull the discussion.

Usage

const res = await fetch('https://api.yepapi.com/v1/reddit/subreddit-posts', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"subreddit": "python", "sort": "top", "time": "week"}),
});
const { data } = await res.json();
console.log(data);

curl -X POST https://api.yepapi.com/v1/reddit/subreddit-posts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subreddit": "python", "sort": "top", "time": "week"}'

import requests

res = requests.post(
    "https://api.yepapi.com/v1/reddit/subreddit-posts",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"subreddit": "python", "sort": "top", "time": "week"},
)
print(res.json()["data"])

Request Body

Parameter	Type	Required	Description	Default
`subreddit`	`string`	Yes	Subreddit name — `python`, `r/python`, or a reddit.com/r/python URL (2–21 characters)	—
`sort`	`string`	No	One of: `hot`, `new`, `top`, `controversial`	`hot`
`time`	`string`	No	Time window, only used with `sort: "top"` or `"controversial"`. One of: `hour`, `day`, `week`, `month`, `year`, `all`	`day`
`cursor`	`string`	No	`cursor` from the previous response, to fetch the next page	—

Response

{
  "ok": true,
  "data": {
    "cursor": "t3_1xg0wft",
    "posts": [
      {
        "author": "me_myself_ai",
        "created_at": "2026-10-24T07:09:01+00:00",
        "created_utc": 1792825741,
        "domain": "self.Python",
        "flair": "News",
        "id": "1xe1zp2",
        "images": [],
        "is_self": true,
        "is_video": false,
        "locked": false,
        "name": "t3_1xe1zp2",
        "num_comments": 53,
        "num_crossposts": 0,
        "over_18": false,
        "permalink": "https://www.reddit.com/r/Python/comments/1xe1zp2/cve2026111497_if_you_run_a_python_server_you/",
        "score": 230,
        "selftext": "The \"HTTP2Shell\" vulnerability affects servers that know how to speak Google's 'brotli' compression protocol, which would likely make its way into your server through an innoccuous-sounding speedup de…",
        "spoiler": false,
        "stickied": false,
        "subreddit": "Python",
        "thumbnail": null,
        "title": "[CVE-2026-111497] If you run a python server, you should update it right now",
        "upvote_ratio": 0.95,
        "url": "https://www.reddit.com/r/Python/comments/1xe1zp2/cve2026111497_if_you_run_a_python_server_you/",
        "video_url": null
      },
      {
        "author": "japaget",
        "created_at": "2026-10-26T23:34:42+00:00",
        "created_utc": 1793057682,
        "domain": "self.Python",
        "flair": "News",
        "id": "1xgcu6d",
        "images": [
          "https://external-preview.redd.it/jo_taLBpL8KctIyrekKwKwNQmqG7Jnqc0zvyiwBwffE.png?auto=webp&s=1ec991a52359a89239485c53abe8369ecbbcb6d3"
        ],
        "is_self": true,
        "is_video": false,
        "locked": false,
        "name": "t3_1xgcu6d",
        "num_comments": 34,
        "num_crossposts": 0,
        "over_18": false,
        "permalink": "https://www.reddit.com/r/Python/comments/1xgcu6d/python_3152_31410_31318_31216_and_31118_are_out/",
        "score": 224,
        "selftext": "See [https://blog.python.org/2026/10/python-3152-31410-31318-31216-31118/](https://blog.python.org/2026/10/python-3152-31410-31318-31216-31118/) .  This is another security update that addresses the […",
        "spoiler": false,
        "stickied": false,
        "subreddit": "Python",
        "thumbnail": null,
        "title": "Python 3.15.2, 3.14.10, 3.13.18, 3.12.16 and 3.11.18 are out",
        "upvote_ratio": 0.96,
        "url": "https://www.reddit.com/r/Python/comments/1xgcu6d/python_3152_31410_31318_31216_and_31118_are_out/",
        "video_url": null
      }
    ]
  }
}

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.posts`	`object[]`	Posts in the subreddit
`data.posts[].id`	`string`	Post ID (base36)
`data.posts[].name`	`string`	Fullname, `t3_` + ID — the same value Reddit uses in cursors
`data.posts[].title`	`string`	Post title
`data.posts[].author`	`string`	Author username
`data.posts[].subreddit`	`string`	Subreddit name without `r/`
`data.posts[].permalink`	`string`	Full reddit.com URL of the post — pass it to `/v1/reddit/post` or `/v1/reddit/post-comments`
`data.posts[].url`	`string`	Link target: the external URL, image, or the post itself for text posts
`data.posts[].domain`	`string`	Domain of `url` (`self.<subreddit>` for text posts)
`data.posts[].selftext`	`string`	Body of a text post in Markdown (empty for link posts)
`data.posts[].score`	`number`	Net upvotes
`data.posts[].upvote_ratio`	`number`	Share of upvotes, 0–1
`data.posts[].num_comments`	`number`	Comment count
`data.posts[].num_crossposts`	`number`	Crosspost count
`data.posts[].created_utc`	`number`	Unix timestamp (seconds)
`data.posts[].created_at`	`string`	ISO 8601 timestamp
`data.posts[].flair`	`string \| null`	Post flair text
`data.posts[].is_self`	`boolean`	Text post (no external link)
`data.posts[].is_video`	`boolean`	Reddit-hosted video
`data.posts[].over_18`	`boolean`	Marked NSFW
`data.posts[].spoiler`	`boolean`	Marked as spoiler
`data.posts[].stickied`	`boolean`	Pinned by moderators
`data.posts[].locked`	`boolean`	Comments locked
`data.posts[].thumbnail`	`string \| null`	Thumbnail image URL
`data.posts[].images`	`string[]`	Full-size image URLs (preview images and gallery items)
`data.posts[].video_url`	`string \| null`	MP4 URL for Reddit-hosted videos
`data.cursor`	`string \| null`	Cursor for the next page

Pagination

Each response includes a cursor. Send the same request again with that value in cursor to get the next page. When cursor is null, there are no more results. A query with no matches returns 200 with an empty list and cursor: null. Every page is a separate $0.01 call.

Caching

Responses are cached for 15 minutes.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	`subreddit` is invalid, or `sort` / `time` is not an allowed value
`429`	`RATE_LIMITED_UPSTREAM`	Too many requests in a short burst — retry after a few seconds
`502`	`UPSTREAM_ERROR`	Temporary problem fetching data from Reddit — retry

Failed calls are not charged.

A subreddit that doesn't exist or has no posts for the chosen window returns 200 with an empty posts list.

Reddit Comments API — comments on any post from this list
Subreddit Comments — the latest comments across the whole subreddit
Subreddit Info — member count and settings

Subreddit Posts API

On this page