# Reddit (/docs/reddit)

Reddit subreddit feeds, community details, post bodies, full comment trees, video transcripts, three kinds of search, and a one-call listening sweep

Reddit is the richest source of unprompted opinion on the API, and these endpoints cover it end to end: a community's feed, its own stats and rules, a post's body, the whole nested comment tree beneath it, video transcripts, three different searches, and a composite that does a listening sweep in one call.

Base URL: `/v1/reddit/...`

  **Reddit search is the slowest social search on the API, 10 to 12 seconds, and
  its relevance is loose.** Treat `omni-search` as a voice-of-customer sweep,
  not a precision ranking: you are trading exactness for coverage of what people
  actually said. Set client timeouts accordingly, or stream it.

## Quickstart

### 1. Size up a community

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/details?subreddit=technology" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Read its feed

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/reddit/subreddit?subreddit=technology" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (`computed.labels`, `computed.relevance`) by default at no extra credits; see [Labels](/docs/labels.md).

## Communities

| Endpoint                           | Credits | What it returns                                              | Key parameters                            |
| ---------------------------------- | ------- | ------------------------------------------------------------ | ----------------------------------------- |
| `GET /v1/reddit/subreddit/details` | 1       | Subscriber count, description, rules, and community settings | `subreddit` or `url`                      |
| `GET /v1/reddit/subreddit`         | 1       | The community feed: titles, scores, comment counts, flair    | `subreddit`, `sort`, `timeframe`, `after`, `label`, `judgments` |

**`timeframe` only works with `sort=top`.** On `subreddit`, a `timeframe` with any other sort is ignored by Reddit. Omitting `sort` entirely auto-selects `top` for you, so `?subreddit=technology&timeframe=week` behaves as you would expect, but `?subreddit=technology&sort=new&timeframe=week` quietly gives you the unfiltered new feed.

## Posts and comments

| Endpoint                         | Credits | What it returns                                                           | Key parameters          |
| -------------------------------- | ------- | ------------------------------------------------------------------------- | ----------------------- |
| `GET /v1/reddit/post`            | 1       | One post **including the body text**, plus score, upvote ratio, flair     | `url`                   |
| `GET /v1/reddit/post/comments`   | 5       | The full nested comment tree, each comment with author, score, and awards | `url`, `cursor`, `trim`, `label`, `judgments` |
| `GET /v1/reddit/post/transcript` | 10      | A video post's captions, both raw and as plain text                       | `url`, `language`       |

The feed and search endpoints leave the body text out, so `post` is the call that gets it.

`post/comments` is the one advanced-tier endpoint on this platform, because it expands the whole tree rather than a page. On very large threads the response reports which branches were left unopened. When Reddit publishes no captions, `post/transcript` comes back empty and flagged rather than as an error.

**Count the comments with `data.comments_returned`, not `items.length`.** `items[]` holds the top-level comments only, and each reply sits under its parent's `comment.replies[]`, so a thread of 56 comments can come back as 11 rows. `comments_returned` counts every comment in the response, replies included, and is the number to compare with the post's comment count.

## Search

| Endpoint                          | Credits | What it returns                                                       | Key parameters                                                |
| --------------------------------- | ------- | --------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET /v1/reddit/search`           | 1 to 40 | One keyword across all of Reddit, with subreddit names and permalinks; up to 1,000 posts in one call with `limit` | `query`, `sort`, `timeframe`, `limit` (1-1000), `since`, `after`, `label`, `relevance`, `judgments` |
| `GET /v1/reddit/subreddit/search` | 1 to 26 | The same search confined to one community                             | `subreddit`, `query`, `sort`, `timeframe`, `cursor`           |
| `GET /v1/reddit/subreddits/search` | 1 to 26 | Which communities discuss a topic; `include=details` adds the creation date, weekly activity, rules and language per community | `query`, `include`, `limit` (1-25), `cursor` |
| `GET /v1/reddit/omni-search`      | 5 to 9  | A listening sweep: search, thread comments, and a subreddit roll-up   | `query`, `threads` (1-8, default 8), `subreddit`, `timeframe` |

`subreddits/search` is the call that comes before the other three: it answers which communities discuss a subject, and `author.id` on each row is the exact `subreddit` parameter the rest of this platform takes. On a plain call it returns the name, subscriber count, description and icon for 1 credit. Add `include=details` and every community on the page is joined, in the same call, to `subreddit/details`, so the creation date, weekly active users, weekly contributions, rules and language land on each row: 1 credit for the page plus 1 per community filled from a fresh lookup, 26 at most. Communities already in cache are filled for free, communities that could not be filled are refunded, and `limit=N` (1 to 25) takes the top N and caps the extra credits with it. The response carries a `data.hydration` block with the rows looked up, filled and served from cache, the credits held and kept, and the milliseconds the lookups added. Allow 3 to 9 seconds on a fresh page, never more than 12, and nothing when the communities are already cached.

The keyword search lanes are metered too: the page itself is 1 credit, and `limit` (below) and `include_body=true` are what take it higher. That flag is rarely worth reaching for on `/v1/reddit/search`, which already returns bodies on the rows themselves; it reserves up to 25 extra credits, refunds every one it does not spend, and a link post has no body to fetch and is not charged for. On the scoped lane the bodies are genuinely absent, so the flag does something, and `/v1/reddit/search?query=subreddit:<name> <terms>` gets you the same bodies for 1 credit if you can live with a different index.

### More than one page in one call

`/v1/reddit/search?limit=N` with `N` from 26 to 1,000 reads Reddit's own search index once and returns up to `N` posts for the query, sort and timeframe, newest first with `sort=new`. It costs 1 credit per 25 posts returned, never less than 1: the call holds `N / 25` credits and refunds the rest once the posts are counted. Reddit stops one query at about 1,000 posts, so this answer has no next page. `max_items` does the same thing for you on this endpoint (`max_items=300` is one call of up to 300 posts), and at 25 or below the ordinary page comes back exactly as without `limit`.

To collect more than one query's ceiling on a busy keyword over a day, repeat the call with `sort=new` and `since` set to the time of your previous run. Only posts inside the window are returned and only those are billed, so a call that finds 70 new posts costs 3 credits. `seen=<your-id>` does the same by post id instead of by time.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/reddit/search?query=chatgpt&sort=new&limit=1000&since=2026-10-26T06:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"
```

Scoped search is the one to reach for when a term means something different in r/investing than in r/wallstreetbets. One caveat on `timeframe`: it narrows the window on `sort=relevance`, `sort=top` and the comment-count sort, and does nothing on `sort=new`, which is already ordered newest-first and returns recent posts regardless.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/search?subreddit=technology&query=data%20api&sort=top&timeframe=month" \
  -H "x-api-key: YOUR_API_KEY"
```

### The listening sweep

`GET /v1/reddit/omni-search` is what you would otherwise build by hand: search, then a comments call per thread, then an aggregation. It does all three and returns threads with their top comments inline, capped at 15 a thread, plus a per-community tone label in the roll-up.

**Pricing is metered and the floor is 5, not 1.** It bills 1 credit per search page plus 1 credit per successfully expanded thread, with a minimum of 5 credits. A thread that fails to expand is not billed, and the unused thread ceiling is refunded. `threads` is the lever: 8 threads is a 9-credit ceiling, and lowering it lowers the ceiling.

`subreddit` scopes the whole sweep to one community, and `next_cursor` resumes the search. Send `Accept: text/event-stream` and it streams each thread as its comments land instead of making you wait.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/reddit/omni-search?query=headless%20cms&threads=5&timeframe=month" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

**Spell subreddit names as Reddit does on `subreddit/details`.** The main source for that endpoint is case-sensitive, and a non-canonical spelling falls through to a second source that answers with the core fields but without the weekly-activity numbers. Use the canonical casing (`AskReddit`, not `askreddit`) to get the whole object. The same applies inside `subreddits/search?include=details`, where each row carries Reddit's own casing: a community the main source cannot answer still gets its creation date and language from the second source, and that row is billed as filled while its weekly numbers and rules stay empty.

**Reddit's ad-library endpoints are disabled upstream** and return a `503` at no charge. For ad-library work, the Facebook, Google, and TikTok ad libraries are live.

**Pagination is not uniform.** `subreddit` and `search` page with `after`; `subreddit/search`, `post/comments`, and `omni-search` page with `cursor`.

**Identifiers split three ways.** `subreddit`, `subreddit/search`, and `subreddit/details` take a subreddit name, and `details` also accepts a `url`; `post`, `post/comments`, and `post/transcript` take a post `url`; the searches take a `query`.

**Reddit feeds other surfaces too.** It is one of the sources behind [`/v1/search/everywhere`](/docs/search/everywhere.md) and the leg that most Prism brand composites lean on.

## Labels

These lists label their rows by default, at no extra credit. On `/v1/reddit/post/comments`, each comment carries `sentiment`, `question`, `purchase_intent` and `complaint` on `computed.labels`. On `/v1/reddit/search` and `/v1/reddit/subreddit`, each row carries `sponsored`, `intent` and `niche`. `/v1/reddit/search` also scores each row's relevance to your `query` on `computed.relevance`, without dropping or reordering anything; add `relevance=filter` to drop the rows that are about something else, still free. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes, rows still `pending`, and the labels you can add with `label=`.

## Next steps

- [Pagination](/docs/pagination.md): Cursor and page walks, and what has_more actually means.
- [Credits](/docs/credits.md): What each tier costs and when a call is refunded.
- [Which endpoint should I use?](/docs/choosing-endpoints.md): Picking between one subreddit, all of Reddit, and the wider forum web.
- [API reference](/docs/api-reference.md): Every parameter and response field, endpoint by endpoint.
- [Universal search](/docs/search/everywhere.md): One keyword across Reddit and every other source at once.