Search Reddit Posts Globally or by Subreddit

Search posts globally or restrict to a subreddit. Mirrors the "Posts" tab on reddit.com search.

Choosing a search endpoint

Reddit splits search across tabs, and so do we. Each endpoint returns a different object, so pick by what you want back rather than by what you are searching for.

Only this endpoint takes a subreddit parameter. The others search site-wide. To confine a media search to one subreddit, put Reddit's subreddit: operator in the query instead, as shown on the Search Media page.

Query Parameters

Advanced filters

Reddit's search cannot filter on score, comment count, media type, or post flags server-side, so those filters are applied to the page the search returns (the same model as pullpush). A filter can therefore return far fewer than limit results per page, so when any filter is passed the response adds a meta object with completeness counts and you paginate with after for more:

"meta": { "fetched": 25, "returned": 3, "filtered_out": 22, "filters": { "min_score": 500 } }

fetched is how many the page held, returned how many passed your filters, filtered_out the difference. When no filter is passed the response keeps the plain { posts, after } shape.

Sort and freshness

sort=relevance (and sort=top) blend text match with a post's score, so on a broad or long-lived query the highest-upvoted posts can outrank the closest matches. The t time window bounds which posts are eligible and it does apply to relevance on search. When you omit t, Reddit defaults to all, which lets old viral posts surface. Pass a bounded window such as t=week or t=month to keep a relevance search recent and on-topic, or use sort=new for a strict reverse-chronological feed.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.redditapis.com/api/reddit/search?q=twitter+api+alternative&sort=relevance&t=all"

const response = await fetch(
  "https://api.redditapis.com/api/reddit/search?q=twitter+api+alternative&sort=relevance&t=all",
  { headers: { Authorization: "Bearer TOKEN" } }
);

import requests

response = requests.get(
    "https://api.redditapis.com/api/reddit/search",
    params={"q": "twitter api alternative", "sort": "relevance", "t": "all"},
    headers={"Authorization": "Bearer TOKEN"},
)

Response Shape

Same shape as /api/reddit/posts, posts: [...] + after cursor. See that page for the per-post field reference (upvotes, comments, link_url, is_crosspost, crosspost_origin, etc.).

When after comes back empty

An empty cursor means there is no next page to ask for. It does not always mean you have every post: Reddit often stops serving a busy listing long before it runs out. Paging r/all on 2026-08-14 stopped after 400 posts covering about a minute of a feed that plainly holds more.

The response tells you which happened. When after is null it also carries listing_status, which reads complete, truncated or unknown. Only complete means you have everything; treat the other two as a partial answer and widen your search rather than stopping. The full field list and what to do about each answer is in Pagination depth.