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 Failed requests are free
About this endpoint
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, top, or comment-count. 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). Bill from 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.
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. See the API docs for parameter enums.
What do sortBy and timeframe accept?
sortBy: relevance, new, top, or comment-count (most-commented first). 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.