# Reddit Subreddits Search API (https://www.socialcrawl.dev/platforms/reddit/subreddits-search)

> 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`. When the main source is unavailable, a backup answers the first page with the same fields and no `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.

TL;DR: `GET /v1/reddit/subreddits/search` costs 1 credit for the page. include=details holds 1 credit per row, at most 25 (or `limit`), and keeps only the rows filled from a fresh lookup, so a page is at most 26 credits; rows served from cache are free, unfilled rows are refunded, and a repeat within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Topic or keyword to find communities for. |
| `cursor` | no | Cursor to get more results. Get 'cursor' from the previous response. |
| `include` | no | 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. (details) |
| `limit` | no | 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. |
| `max_pages` | no | 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. |
| `max_items` | no | 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. |
| `max_credits` | no | 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/reddit/subreddits/search" \
  --data-urlencode "query=machine learning" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I find subreddits about a topic?

Send a GET request to /v1/reddit/subreddits/search with a query. Each row carries the community name at author.id, the subscriber count, description, icon and NSFW flag, up to 25 communities per page.

### How do I get weekly active users for each community?

Add include=details to the same call. Every community on the page is joined to the subreddit details lookup, so the creation date, weekly active users, weekly contributions, rules and language land on each row.

### How much does the Subreddit Search API cost?

A plain search costs 1 credit on the standard tier. With include=details you pay the page price plus one credit per community filled from a fresh lookup, so at most 26 credits; communities already in cache are free and ones that could not be filled are refunded.

### Can I cap how many communities are returned?

Yes. limit takes the top N communities of the page, 1 to 25, and with include=details it caps the extra credits at N as well, so asking for five holds five extra credits rather than the whole ceiling.

### Can I feed the results into the other Reddit endpoints?

Yes. author.id is the bare community name in Reddit's own casing, which is exactly the subreddit parameter that /v1/reddit/subreddit, /v1/reddit/subreddit/details and /v1/reddit/subreddit/search take.

See the full Reddit API: https://www.socialcrawl.dev/platforms/reddit

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- Which subreddits discuss a topic, and how active are they?
- How do I find subreddits about a topic programmatically?
- What does the SocialCrawl Subreddit Search API return?