Reddit Search API

Reddit Search API — search Reddit posts across all subreddits or inside one subreddit, sorted by relevance, hot, top, new, or comment count. JSON, $0.01 per call.

POST/v1/reddit/search

$0.01/call

The Reddit Search API finds posts matching a keyword across all of Reddit, or inside a single subreddit when you pass subreddit. Results come back as structured JSON — title, author, score, comment count, images, and the full post URL — so you can monitor brand mentions, research topics, or feed posts into an LLM without scraping Reddit or registering a Reddit app. You only need your YepAPI key.

To search for communities instead of posts, use Search Subreddits; for accounts, use Search Users.

Usage

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

curl -X POST https://api.yepapi.com/v1/reddit/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "asyncio", "subreddit": "python", "sort": "new"}'

import requests

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

Request Body

Parameter	Type	Required	Description	Default
`query`	`string`	Yes	Search text (max 512 characters)	—
`subreddit`	`string`	No	Limit results to one subreddit — `python`, `r/python`, or a subreddit URL	—
`sort`	`string`	No	One of: `relevance`, `hot`, `top`, `new`, `comments`	`relevance`
`time`	`string`	No	Time window, only used with `sort: "top"`. 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_1rhul46",
    "posts": [
      {
        "author": "kirara0048",
        "created_at": "2026-10-30T08:05:21+00:00",
        "created_utc": 1793347521,
        "domain": null,
        "flair": null,
        "id": "t3_1xj9fse",
        "images": [],
        "is_self": false,
        "is_video": false,
        "locked": false,
        "name": null,
        "num_comments": 44,
        "num_crossposts": null,
        "over_18": false,
        "permalink": "https://www.reddit.com/r/Python/comments/1xj9fse/pep_851_add_listdiscard/",
        "score": 159,
        "selftext": "PEP 851 – Add list.discard()\n\nhttps://peps.python.org/pep-0851/\n\nDiscussions-To: Discourse thread\n\nAbstract\n\nAdd list.discard(x), which removes the first item equal to x if one is present and does not…",
        "spoiler": false,
        "stickied": false,
        "subreddit": "Python",
        "thumbnail": null,
        "title": "PEP 851 – Add list.discard()",
        "upvote_ratio": null,
        "url": null,
        "video_url": null
      },
      {
        "author": "Professional-Run3614",
        "created_at": "2026-10-13T06:08:07+00:00",
        "created_utc": 1791871687,
        "domain": null,
        "flair": null,
        "id": "t3_1x4ozs0",
        "images": [],
        "is_self": false,
        "is_video": false,
        "locked": false,
        "name": null,
        "num_comments": 20,
        "num_crossposts": null,
        "over_18": false,
        "permalink": "https://www.reddit.com/r/Python/comments/1x4ozs0/lessons_from_building_a_live_iot_ingestion_server/",
        "score": 6,
        "selftext": "I've been working on a telematics backend that ingests TCP sensor data from heavy equipment. The pipeline is Python → local disk spool → RabbitMQ → PostgreSQL.\n\nA few things we learned the hard way:\n\n…",
        "spoiler": false,
        "stickied": false,
        "subreddit": "Python",
        "thumbnail": null,
        "title": "Lessons from building a live IoT ingestion server in Python",
        "upvote_ratio": null,
        "url": null,
        "video_url": null
      }
    ]
  }
}

Response Fields

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`data.posts`	`object[]`	Matching posts
`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, `null` on the last 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. Repeating the same request within that window returns the cached result.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	`query` is missing or too long, or `sort` / `time` / `subreddit` is invalid
`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.

Reddit Post API — full details for one post from its permalink
Reddit Comments API — the comment tree for a post
Subreddit Posts API — browse a subreddit's hot, new, top, or controversial posts

Reddit Search API

On this page