# Reddit (/docs/reddit)



Reddit [#reddit]

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 whole listening sweep in one call.

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

<Callout>
  Searching one subreddit (

  `/v1/reddit/subreddit/search`

  ), all of Reddit (

  `/v1/reddit/search`

   or 

  `/v1/reddit/omni-search`

  ), or the wider forum web (

  `/v1/search/forums`

  )? See 

  [Which endpoint should I use?](/docs/choosing-endpoints.md)

  .
</Callout>

How do I get started with Reddit data? [#how-do-i-get-started-with-reddit-data]

1\. Size up a community [#1-size-up-a-community]

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

2\. Read its feed [#2-read-its-feed]

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

3\. Read computed fields [#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.

Three searches, three scopes [#three-searches-three-scopes]

* **`GET /v1/reddit/search`** (1cr) — one keyword across all of Reddit. Returns titles, scores, comment counts, subreddit names, and permalinks.
* **`GET /v1/reddit/subreddit/search`** (1cr) — the same search confined to one community. Takes `subreddit` plus a `query`, with `sort`, `timeframe`, and `cursor`. This is the one to reach for when a term means something different in r/investing than in r/wallstreetbets.
* **`GET /v1/reddit/omni-search`** (5-9cr, metered) — a listening sweep rather than a search. It runs the search, expands the top threads' comments in parallel, and rolls up which subreddits are talking with a per-community tone label.

```bash
# Keyword inside one community
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/search?subreddit=technology&query=data%20api&sort=top&timeframe=month" \
  -H "x-api-key: sc_your_api_key_here"
```

The listening sweep [#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 the subreddit 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` (1-8, default 8) 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
curl "https://www.socialcrawl.dev/v1/reddit/omni-search?query=headless%20cms&threads=5&timeframe=month" \
  -H "x-api-key: sc_your_api_key_here"
```

<Callout type="warn">
  **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.
</Callout>

Posts and comments [#posts-and-comments]

* **`GET /v1/reddit/post`** (1cr) — one post from its `url`, **including the body text**, which the feed and search endpoints leave out. Also score, upvote ratio, comment count, flair, author, thumbnail, and timestamp.
* **`GET /v1/reddit/post/comments`** (**5cr**) — the full comment tree, each comment with author, body, score, direct-reply count, awards, timestamp, and its nested replies. This is the one advanced-tier endpoint on the platform, because it expands the whole tree rather than a page: on very large threads the response reports which branches were left unopened.
* **`GET /v1/reddit/post/transcript`** (10cr) — the transcript of a video post, both the raw caption file and a plain-text version. When Reddit publishes no captions the transcript comes back empty and flagged rather than as an error.

Two gotchas that cost people a call [#two-gotchas-that-cost-people-a-call]

**`timeframe` only works with `sort=top`.** On `GET /v1/reddit/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.

**Subreddit names are case-sensitive on `subreddit/details`.** Spell the name exactly as Reddit does or the lookup misses.

What Reddit data can I access? [#what-reddit-data-can-i-access]

<PlatformEndpoints platform="reddit" />

<Callout>
  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.
</Callout>

What should I know about Reddit data? [#what-should-i-know-about-reddit-data]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `subreddit`, `subreddit/search`, and `subreddit/details` take a `subreddit` name (`details` also accepts a `url`); `post`, `post/comments`, and `post/transcript` take a post `url`; the searches take `query`
* Pagination is `after` on `subreddit` and `search`, and `cursor` on `subreddit/search`, `post/comments`, and `omni-search`
* Reddit is also one of the sources behind [`/v1/search/everywhere`](/docs/search/everywhere.md) and the leg that most Prism brand composites lean on

Official Reddit Resources [#official-reddit-resources]

* [Reddit API Documentation](https://www.reddit.com/dev/api/) — Official Reddit developer documentation
* [Reddit Data API](https://support.reddithelp.com/hc/en-us/articles/16160228947092-Reddit-Data-API-Wiki) — Data API wiki