Reddit Search API
Site-wide post keyword search — query across public Reddit, then fan out to comments or a known subreddit when you need scope.
GET /v1/reddit/search1 credit per successful request.
About this endpoint
Product research and brand listening on Reddit usually start with a phrase that shows up in many communities at once: switching stories, pricing complaints, "alternative to X," launch day threads. Scoping to one subreddit too early hides the signal. Hand-browsing Reddit search does not scale, and standing up Reddit's own OAuth client for a read-only research cron is often more process than the answers are worth.
`GET /v1/reddit/search` takes a required `query` string (1–512 characters) and returns matching public posts under `data.posts`, with the query echoed on `data.query` and a page row count on `data.totalResults`. Optional `sortBy` accepts `relevance`, `new`, or `top`. Optional `timeframe` accepts `all`, `day`, `week`, `month`, or `year` (useful with `top` or time-bounded recency). Pass `cursor` when `data.page.hasMore` is true; keep the same query, sort, and timeframe. Optional `trim` requests a smaller shape when available. Each post can include id, name, title, author, subreddit / subredditPrefixedName, url, permalink, bodyText, score, upvotes, upvoteRatio, commentCount, createdAt, isVideo, and subredditSubscriberCount when Reddit exposes them.
`data.totalResults` counts rows on the current page, not the size of Reddit's entire index. End-of-results comes from `data.page.hasMore`, not from totalResults hitting zero alone. An empty `posts` array with `hasMore: false` is a valid success for a query that matched nothing (still billed). Pricing is on the credit badge on this page; trust `meta.creditsCharged`.
This route is global post search. To stay inside one community, use `GET /v1/reddit/subreddits/search` (required `subreddit`, optional query). For that community's ranked feed without a search query, use `GET /v1/reddit/subreddits/{subreddit}/posts`. After you have a post URL, pull comments or transcript on the post routes. Same Social Fetch API key.
For a full research sprint (query matrix, comment pulls, credit math), see /guides/reddit-product-research and /docs/recipes/reddit-research. Prefer a browser spot check first? Use /tools/reddit-research.
Reddit Search API FAQ
How do I search Reddit posts site-wide via API?
Call GET /v1/reddit/search with x-api-key and a required query parameter. Optionally add sortBy, timeframe, cursor, and trim. Read data.posts, data.totalResults, and data.page. Full parameter enums are in the API docs.
What do sortBy and timeframe accept?
sortBy: relevance, new, or top. timeframe: all, day, week, month, or year. Pair timeframe with top (or other sorts) when you care about a window. Keep both values identical across paginated pages.
What fields does each Reddit search post include?
Posts can include id, name, title, author, subreddit, subredditPrefixedName, url, permalink, bodyText, score, upvotes, upvoteRatio, commentCount, createdAt, isVideo, and subredditSubscriberCount when available. Coverage follows public Reddit search for that hit.
What does data.totalResults mean?
It is the count of posts returned on this page (for example 25), not a guarantee of how many matches exist site-wide. Use data.page.hasMore and nextCursor to continue. Do not stop solely because totalResults looks small.
What happens when no posts match?
HTTP 200 with data.posts as [], totalResults 0, and hasMore false. That is a completed empty page, not a failure. Persist meta.requestId if you need to debug the query.
How much does Reddit post search cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth. Each paginated page is a separate billed request.
Global search vs subreddit search vs subreddit posts?
GET /v1/reddit/search is site-wide keyword search across public posts. GET /v1/reddit/subreddits/search requires a subreddit and optionally a query inside that community. GET /v1/reddit/subreddits/{subreddit}/posts is that community's feed without a search query. Pick by whether you already know the community.
How does pagination work on Reddit search?
When data.page.hasMore is true, pass data.page.nextCursor as the cursor query param on the next request. Keep the same query, sortBy, and timeframe. Do not invent fullnames or after tokens yourself.
Do I need a Reddit OAuth app to search posts?
No. You authenticate to Social Fetch with an API key. The route reads public search results; it does not act on behalf of a logged-in Reddit user or open private subreddits.