Find subreddits by topic
Finds communities by topic. Every other Reddit endpoint on this API needs you to already know the subreddit you want; this is the one that answers which communities discuss a subject. Returns up to 25 communities with the name, the subscriber count, the description, the icon, the NSFW flag and the community URL. author.id is the bare community name in Reddit's own casing, which is exactly what /v1/reddit/subreddit, /v1/reddit/subreddit/details and /v1/reddit/subreddit/search take as their subreddit parameter, so a discovery call feeds a listing call with no re-mapping in between. The row is the same Author shape /v1/reddit/subreddit/details returns. The search surface publishes nothing else, so on a plain call author.joined_at, author.ext.weekly_active_users, author.ext.weekly_contributions, author.ext.rules_text and author.ext.language are null on every row. Send include=details and every row is joined, in the same call, to the details lookup that carries them: the community's creation date, weekly active users, weekly contributions and rules land on each row (rules stay null for a community that publishes none), and the language on most rows (it comes from a second source that can miss a row on a busy page, so treat it as usually present). When the details lookup's main source cannot answer a row, its second source still fills the creation date and the language and that row is billed as filled, but the weekly numbers and the rules stay null on it; data.hydration counts it among the filled rows. Cost: 1 credit for the page plus 1 credit per row filled from a fresh lookup (25 rows, so 26 at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0. Time: a plain call is about 1 second; include=details adds 3 to 9 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. limit=N (1 to 25) takes the top N communities of the page and, with include, caps the extra credits at N. The response carries a hydration block itemising rows, lookups, cache hits, credits and milliseconds. The subscriber count on a search row is the search index's own figure; the join never overwrites a value the row already carries. Note the name: this is subreddits/search and it finds COMMUNITIES, where the singular subreddit/search searches posts INSIDE one community. Paginate with cursor. A query that matches nothing still returns communities rather than an empty list, which is Reddit's own search behaviour, so judge relevance on the rows.
Request
- Base URL: https://www.socialcrawl.dev/v1
- URL: https://www.socialcrawl.dev/v1/reddit/subreddits/search
- Auth: API key in header x-api-key
Query parameters
Topic or keyword to find communities for.
Cursor to get more results. Get 'cursor' from the previous response.
Set to details (one token only) to fill author.joined_at, author.ext.weekly_active_users, author.ext.weekly_contributions, author.ext.rules_text and author.ext.language on every row in this one call (a row the details lookup's main source cannot answer gets only the creation date and the language, and is still billed). Holds 1 credit per row (at most 25, or limit) and keeps only the rows filled from a fresh lookup; rows already in cache and rows that could not be filled are refunded, so the most a call can cost is 1 + rows. Adds 3 to 9 seconds on a fresh page (never more than 12) and nothing when the rows are already cached; read data.hydration for the rows, the credits held and kept, and the time.
Take the top N communities of the page (1 to 25). With include=details it also caps the extra credits at N, so limit=5&include=details holds 6 credits, not 26. It is not a page size: the cursor still advances past the whole page, so rows beyond N are not returned by the next page.
Headers
Send no-cache to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the no-cache directive triggers this. See the Response Schema guide for details.
Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives 409 IDEMPOTENCY_IN_PROGRESS with a Retry-After of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: credits_used becomes 0, idempotent_replay becomes true, and credits_remaining is refreshed to the current balance. A known current balance appears in both the body and X-Credits-Remaining header; no balance row resolves to 0. On a transient lookup failure, body credits_remaining is null and X-Credits-Remaining is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use Accept: application/json when sending this header. The unsupported key-plus-SSE combination is rejected before billing.
Response
Successful response
Example response
{
"success": true,
"platform": "reddit",
"endpoint": "/v1/reddit/subreddits/search",
"credits_used": 1,
"credits_remaining": 4999,
"request_id": "req-abc123",
"idempotent_replay": true,
"meta": {
"hint": {
"code": "search_multi",
"message": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged.",
"method": "GET",
"path": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube"
}
},
"pagination": {
"next_cursor": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0",
"has_more": true,
"page_size": 30,
"stopped_at": "known_id"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.