# 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.

## 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` |

**`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` |
| `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.

## Search

| Endpoint                          | Credits | What it returns                                                       | Key parameters                                                |
| --------------------------------- | ------- | --------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET /v1/reddit/search`           | 1 to 26 | One keyword across all of Reddit, with subreddit names and permalinks | `query`, `sort`, `timeframe`, `after`                         |
| `GET /v1/reddit/subreddit/search` | 1 to 26 | The same search confined to one community                             | `subreddit`, `query`, `sort`, `timeframe`, `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` |

Both search lanes are metered: the page itself is 1 credit, and only `include_body=true` can 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.

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.

**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.

## 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.