SocialCrawl

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
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/details?subreddit=technology" \
  -H "x-api-key: sc_your_key_here"
TypeScript
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);
Python
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
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 wantCall
A community's subscribers, rules and activityGET /v1/reddit/subreddit/details
A community's feedGET /v1/reddit/subreddit
One post with its bodyGET /v1/reddit/post
The comments under a post, replies includedGET /v1/reddit/post/comments
What a video post saysGET /v1/reddit/post/transcript
Posts about a keyword across RedditGET /v1/reddit/search
Posts about a keyword inside one communityGET /v1/reddit/subreddit/search
Comments that mention a phraseGET /v1/reddit/search/comments
Image and video posts for a topicGET /v1/reddit/search/media
Which communities discuss a topicGET /v1/reddit/subreddits/search
A search with threads and top comments in one callGET /v1/reddit/omni-search
An account's karma and cake dayGET /v1/reddit/profile
An account's posts and commentsGET /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 503 at no charge.
  • More than about 1,000 posts for one query. Reddit stops a query there, so repeat the call with since to 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.shares is null on every Reddit list endpoint.
  • Every comment of an enormous thread. data.truncated tells you when more of the thread exists than the response carries.

Communities

EndpointCreditsWhat it returnsKey parameters
GET /v1/reddit/subreddit/details1Subscriber count, description, rules, and community settingssubreddit or url
GET /v1/reddit/subreddit1The community feed: titles, scores, comment counts, flairsubreddit, 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

EndpointCreditsWhat it returnsKey parameters
GET /v1/reddit/post1One post including the body text, plus score, upvote ratio, flairurl
GET /v1/reddit/post/comments5The full nested comment tree, each comment with author, score, and awards, plus the post itself at data.posturl, cursor, trim, label, judgments
GET /v1/reddit/post/transcript10A video post's captions, both raw and as plain texturl, 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

EndpointCreditsWhat it returnsKey parameters
GET /v1/reddit/profileRosterThe karma split, cake day, bio, avatar, banner, trophy count and follower counthandle
GET /v1/reddit/profile/postsRosterThe account's submissions, newest first, up to 25 a pagehandle, sort, timeframe, cursor
GET /v1/reddit/profile/comments2 eachThe account's comment history, newest first, read from its own listinghandle, 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.

EndpointCreditsWhat it returnsKey parameters
GET /v1/reddit/search1 to 40One keyword across all of Reddit, with subreddit names and permalinks; up to 1,000 posts in one call with limitquery, sort, timeframe, limit (1-1000), since, after, label, relevance, judgments
GET /v1/reddit/subreddit/search1 to 26The same search confined to one communitysubreddit, query, sort, timeframe, cursor
GET /v1/reddit/subreddits/search1 to 26Which communities discuss a topic; include=details adds the creation date, weekly activity, rules and language per communityquery, include, limit (1-25), cursor
GET /v1/reddit/search/commentsRosterComments found by phrase, each with its parent post inline; author:name and subreddit:name work in queryquery, sort, cursor, since, until
GET /v1/reddit/search/mediaRosterPosts that carry an image, video or gallery, up to 25 a pagequery, sort, timeframe, cursor
GET /v1/reddit/omni-search5 to 9A listening sweep: search, thread comments, and a subreddit roll-upquery, 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
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
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.

EndpointPathCredit Tier
Reddit VoC sweep: one keyword → threads across all of Reddit with subreddit attribution and top comments inline./v1/reddit/omni-searchstandard (5-9cr)metered
Get a Reddit post/v1/reddit/poststandard (1cr)
Get a Reddit user profile/v1/reddit/profilestandard (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/commentsstandard (2-200cr)metered
List a Reddit user's posts/v1/reddit/profile/postsstandard (1cr)
Search Reddit posts/v1/reddit/searchstandard (1-48cr)metered
Search Reddit comments/v1/reddit/search/commentsstandard (1-5cr)metered
Search Reddit image and video posts/v1/reddit/search/mediastandard (1cr)
List Reddit subreddit posts/v1/reddit/subredditstandard (1-5cr)metered
Get Reddit subreddit details/v1/reddit/subreddit/detailsstandard (1cr)
Search within a subreddit/v1/reddit/subreddit/searchstandard (1-26cr)metered
Find subreddits by topic/v1/reddit/subreddits/searchstandard (1-26cr)metered
List Reddit post comments/v1/reddit/post/commentsadvanced (5-9cr)metered
Get a Reddit video post transcript/v1/reddit/post/transcriptpremium (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

PathRows per pageDate windowOne call collects
/v1/reddit/omni-searchvariesnoneone page a call
/v1/reddit/post/commentsvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/reddit/profile/commentsvariessince and until, applied to each page fetchedlimit up to 100
/v1/reddit/profile/postsvariessince and until. Newest first with sort=new, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/reddit/searchabout 25since 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/commentsabout 24since and until. Newest first with sort=new, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/reddit/search/mediaabout 25since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/reddit/subredditabout 15since and until. Newest first with sort=new, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/reddit/subreddit/searchvariessince and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/reddit/subreddits/searchvariesnoneup 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.

PathTypical (median)95% finish withinTimeout to set
/v1/reddit/omni-search15 s48 s73 s
/v1/reddit/post0.7 s18 s30 s
/v1/reddit/post/comments3.4 s19 s38 s
/v1/reddit/profile11 s13 s22 s
/v1/reddit/search5.8 s9.4 s22 s
/v1/reddit/search/comments4.0 s28 s55 s
/v1/reddit/subreddit2.6 s8.4 s14 s
/v1/reddit/subreddit/details3.6 s32 s52 s
/v1/reddit/subreddit/search2.2 s8.1 s13 s
/v1/reddit/subreddits/search3.9 s15 s29 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. Use AskReddit, not askreddit.
  • Reddit's ad-library endpoints are withdrawn. They return a 503 at no charge. 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. Community calls take a subreddit name. Post calls take a post url. The searches take a query.
  • Reddit feeds other surfaces. It is a source behind /v1/search/everywhere and 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