Reddit data API
Read communities, posts and comments from Reddit with one key and one response shape.
Reddit holds unprompted opinion in its users' own words. These endpoints cover a community's feed and stats, posts, whole comment trees, accounts, video transcripts, several searches and a one-call listening sweep.
Your first call
1. Size up a community
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/details?subreddit=technology" \
-H "x-api-key: sc_your_key_here"const url = new URL("https://www.socialcrawl.dev/v1/reddit/subreddit/details");
url.searchParams.set("subreddit", "technology");
const res = await fetch(url, {
headers: { "x-api-key": process.env.SOCIALCRAWL_API_KEY! },
});
const { data } = await res.json();
console.log(data.author.display_name, data.author.followers);import os
import requests
res = requests.get(
"https://www.socialcrawl.dev/v1/reddit/subreddit/details",
headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
params={"subreddit": "technology"},
)
author = res.json()["data"]["author"]
print(author["display_name"], author["followers"])The response is one author object for the community: subscriber count, description, creation date and, under ext, weekly active users, weekly contributions and the rules. Measured on 22/11/2026: this call took about 9 seconds and cost 1 credit.
2. Read its feed
curl "https://www.socialcrawl.dev/v1/reddit/subreddit?subreddit=technology" \
-H "x-api-key: sc_your_key_here"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 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.
What it covers
| What you want | Call |
|---|---|
| A community's subscribers, rules and activity | GET /v1/reddit/subreddit/details |
| A community's feed | GET /v1/reddit/subreddit |
| One post with its body | GET /v1/reddit/post |
| The comments under a post, replies included | GET /v1/reddit/post/comments |
| What a video post says | GET /v1/reddit/post/transcript |
| Posts about a keyword across Reddit | GET /v1/reddit/search |
| Posts about a keyword inside one community | GET /v1/reddit/subreddit/search |
| Comments that mention a phrase | GET /v1/reddit/search/comments |
| Image and video posts for a topic | GET /v1/reddit/search/media |
| Which communities discuss a topic | GET /v1/reddit/subreddits/search |
| A search with threads and top comments in one call | GET /v1/reddit/omni-search |
| An account's karma and cake day | GET /v1/reddit/profile |
| An account's posts and comments | GET /v1/reddit/profile/posts, GET /v1/reddit/profile/comments |
What it does not cover
- Reddit's ad-library endpoints. They are withdrawn and return a
503at no charge. - More than about 1,000 posts for one query. Reddit stops a query there, so repeat the call with
sinceto collect more over time. - An account's following count and submission count, which stay null on
profile, and verification, moderator and employee flags. - Share counts on lists.
post.engagement.sharesis null on every Reddit list endpoint. - Every comment of an enormous thread.
data.truncatedtells you when more of the thread exists than the response carries.
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. Any other sort ignores it. Leave sort out and top is chosen for you, so ?subreddit=technology&timeframe=week works. Adding sort=new to that call quietly returns 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, plus the post itself at data.post | url, cursor, trim, label, judgments |
GET /v1/reddit/post/transcript | 10 | A video post's captions, both raw and as plain text | url, language |
Feed and search rows carry the post body at ext.selftext when Reddit sends it. A link post has none.
post/comments is the one advanced-tier endpoint here, 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, not as an error.
A thread with no comments returns items: [] and a note in data.empty_reason_note, and costs 0 credits. data.post still holds the post, so one call is enough to watch a thread.
Accounts
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/reddit/profile | Roster | The karma split, cake day, bio, avatar, banner, trophy count and follower count | handle |
GET /v1/reddit/profile/posts | Roster | The account's submissions, newest first, up to 25 a page | handle, sort, timeframe, cursor |
GET /v1/reddit/profile/comments | 2 each | The account's comment history, newest first, read from its own listing | handle, limit |
profile/comments costs 2 credits per comment returned, so a quiet account costs less than your limit. It has no cursor, so limit sets the depth. Try GET /v1/reddit/search/comments?query=author:name first, which costs one page for a sample. A username that does not exist returns an empty list from profile/posts and profile/comments. Call profile to tell a missing account from a quiet one.
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/search/comments | Roster | Comments found by phrase, each with its parent post inline; author:name and subreddit:name work in query | query, sort, cursor, since, until |
GET /v1/reddit/search/media | Roster | Posts that carry an image, video or gallery, up to 25 a page | 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 |
Call subreddits/search first. On each row, author.id is the exact subreddit value the other calls take. Add include=details to fill each community from subreddit/details in the same call. That adds the creation date, weekly activity, rules and language for 1 credit per community, 26 at most. Cached communities are free and failed ones are refunded. A data.hydration block reports what was filled. Allow 3 to 9 seconds on a fresh page.
Keyword search is metered: the page itself is 1 credit, and limit and include_body=true raise it. Skip include_body on /v1/reddit/search, whose rows already carry bodies. On subreddit/search bodies are absent, so the flag helps there. /v1/reddit/search?query=subreddit:<name> <terms> gets the same bodies for 1 credit.
More than one page in one call
/v1/reddit/search?limit=N, with N from 26 to 1,000, reads Reddit's index once and returns up to N posts. Use sort=new for newest first. It costs 1 credit per 25 posts returned, never less than 1. Reddit stops one query at about 1,000 posts, so there is no next page. max_items does the same thing.
To follow a busy keyword over days, repeat the call with sort=new and since set to the time of your previous run. Only posts inside the window are returned and billed. seen=<your-id> does the same by post id.
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"The listening sweep
GET /v1/reddit/omni-search replaces a search, a comments call per thread and an aggregation. It returns threads with up to 15 top comments each, plus a tone label per community.
It bills 1 credit per search page plus 1 per expanded thread, with a minimum of 5. A thread that fails to expand is not billed. threads sets the ceiling, so 8 threads is 9 credits. subreddit scopes the sweep and next_cursor resumes it. Send Accept: text/event-stream to stream each thread as its comments land.
curl "https://www.socialcrawl.dev/v1/reddit/omni-search?query=headless%20cms&threads=5&timeframe=month" \
-H "x-api-key: YOUR_API_KEY"Questions people ask
Does post/comments return only the top-level comments?
No. GET /v1/reddit/post/comments opens nested replies and returns the whole tree in one call. items[] holds the top-level comments. Every reply sits under its parent in comment.replies[], with its depth at ext.depth. Compare data.comments_returned with the post's comment count, not items.length. On a very large thread, data.truncated says whether more exists than the response carries.
Why does a search return only 7 posts?
A search page holds up to 25 posts, and the count varies between calls. Pages of about 7 are common, and a sparse query returns fewer. Self-posts carry their bodies at no extra charge. To read more in one call, send limit from 26 to 1,000. That costs 1 credit per 25 posts returned.
Why does since with sort=relevance fail?
On GET /v1/reddit/search, since ends a newest-first walk at that date, so it sets the newest-first sort for you. Any other sort with since is a free 400. Send sort=new with since, or leave sort out. A call with nothing new costs 1 credit.
How long does a Reddit call take?
Measured on production on 16/11 and 17/11/2026, a plain search page took 1.2 seconds at the median, and 95% of calls finished within 4.6 seconds. A call with limit above 25 took about 8 seconds at the median. omni-search took about 7 seconds, with a tail past 20 seconds. Measured on 22/11/2026, one subreddit/details call took about 9 seconds. Set client timeouts to match. The timeout for each endpoint is under All endpoints.
All endpoints
14 endpoints available.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Reddit VoC sweep: one keyword → threads across all of Reddit with subreddit attribution and top comments inline. | /v1/reddit/omni-search | standard (5-9cr)metered |
| Get a Reddit post | /v1/reddit/post | standard (1cr) |
| Get a Reddit user profile | /v1/reddit/profile | standard (1cr) |
| Read a Reddit account's own comment history, newest first, deeper than any search index reaches. Metered: 2 credits per comment returned, so try /v1/reddit/search/comments?query=author:name first | /v1/reddit/profile/comments | standard (2-200cr)metered |
| List a Reddit user's posts | /v1/reddit/profile/posts | standard (1cr) |
| Search Reddit posts | /v1/reddit/search | standard (1-48cr)metered |
| Search Reddit comments | /v1/reddit/search/comments | standard (1-5cr)metered |
| Search Reddit image and video posts | /v1/reddit/search/media | standard (1cr) |
| List Reddit subreddit posts | /v1/reddit/subreddit | standard (1-5cr)metered |
| Get Reddit subreddit details | /v1/reddit/subreddit/details | standard (1cr) |
| Search within a subreddit | /v1/reddit/subreddit/search | standard (1-26cr)metered |
| Find subreddits by topic | /v1/reddit/subreddits/search | standard (1-26cr)metered |
| List Reddit post comments | /v1/reddit/post/comments | advanced (5-9cr)metered |
| Get a Reddit video post transcript | /v1/reddit/post/transcript | premium (10cr) |
How far back and how deep
Each list returns one page at a time. Send cursor for the next page, or max_items or max_pages to collect several pages in one call. A page size appears only where it has been verified. How paging works
| Path | Rows per page | Date window | One call collects |
|---|---|---|---|
/v1/reddit/omni-search | varies | none | one page a call |
/v1/reddit/post/comments | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/reddit/profile/comments | varies | since and until, applied to each page fetched | limit up to 100 |
/v1/reddit/profile/posts | varies | since and until. Newest first with sort=new, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/reddit/search | about 25 | since and until. Newest first with sort=new, so a walk stops at since. | up to 5,000 rows or 50 pages; limit up to 1,000 |
/v1/reddit/search/comments | about 24 | since and until. Newest first with sort=new, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/reddit/search/media | about 25 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/reddit/subreddit | about 15 | since and until. Newest first with sort=new, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/reddit/subreddit/search | varies | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/reddit/subreddits/search | varies | none | up to 5,000 rows or 50 pages; limit up to 25 |
How long a call takes
Measured on production calls that were not served from the cache, 14/10/2026 to 21/10/2026. A cached call answers faster. Set your client timeout to the value in Timeout to set, so a slow call is not cut off and sent again.
| Path | Typical (median) | 95% finish within | Timeout to set |
|---|---|---|---|
/v1/reddit/omni-search | 15 s | 48 s | 73 s |
/v1/reddit/post | 0.7 s | 18 s | 30 s |
/v1/reddit/post/comments | 3.4 s | 19 s | 38 s |
/v1/reddit/profile | 11 s | 13 s | 22 s |
/v1/reddit/search | 5.8 s | 9.4 s | 22 s |
/v1/reddit/search/comments | 4.0 s | 28 s | 55 s |
/v1/reddit/subreddit | 2.6 s | 8.4 s | 14 s |
/v1/reddit/subreddit/details | 3.6 s | 32 s | 52 s |
/v1/reddit/subreddit/search | 2.2 s | 8.1 s | 13 s |
/v1/reddit/subreddits/search | 3.9 s | 15 s | 29 s |
Platform notes
- Spell subreddit names as Reddit does on
subreddit/details. A non-canonical spelling falls back to a second source that omits the weekly-activity numbers. UseAskReddit, notaskreddit. - Reddit's ad-library endpoints are withdrawn. They return a
503at no charge. The Facebook, Google and TikTok ad libraries are live. - Pagination is not uniform.
subredditandsearchpage withafter.subreddit/search,post/commentsandomni-searchpage withcursor. - Identifiers split three ways. Community calls take a subreddit name. Post calls take a post
url. The searches take aquery. - Reddit feeds other surfaces. It is a source behind
/v1/search/everywhereand most Prism brand composites.
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 relevance to your query on computed.relevance; add relevance=filter to drop off-topic rows. Send judgments=off to skip all of it. See Labels.
Next steps
Pagination
Cursor and page walks, and what has_more actually means.
Credits
What each tier costs and when a call is refunded.
Which endpoint should I use?
Picking between one subreddit, all of Reddit, and the wider forum web.
API reference
Every parameter and response field, endpoint by endpoint.
Universal search
One keyword across Reddit and every other source at once.
