Skip to content

Reddit API

Updated

Read Reddit through one REST API or the hosted MCP server. Search posts and comments, export threads, research subreddits, look up accounts and find people asking for what you sell.

Overview

Base URL: https://api.chatterapi.com/v1. Every Reddit endpoint sits under /v1/reddit, and every call needs your key in the Authorization: Bearer header. See Authentication for how keys work.

  • Read-only. You can't post, comment or vote on Reddit through this API.
  • No Reddit developer account needed. Your one key covers Reddit and X.
  • Same envelope on every call: data, page on list endpoints, credits, requestId and cached. See Credits and Pagination.
  • Agents: each endpoint is also an MCP tool on the hosted server. Dots in the tool id become underscores, so reddit.search is the reddit_search tool.
  • 18+ tools (/v1/reddit/nsfw/...) only answer once the account owner turns on 18+ access in Settings. Until then they return scope_denied.
your first Reddit call
curl "https://api.chatterapi.com/v1/reddit/search?q=best%20crm&time=month&limit=5" \
  -H "Authorization: Bearer $CHATTERAPI_KEY"

Endpoints by chapter

Each endpoint has its own page with parameters, request samples in curl, JavaScript, Python and MCP, a recorded response and the errors it can return. The credits listed are the most a call can cost. We check your balance against that number before the call runs, and charge you only if the call succeeds.

EndpointMethod and pathCredits
Search postsGET /v1/reddit/search2 credits
Search commentsGET /v1/reddit/comments/search2 credits
Search mediaGET /v1/reddit/media/search2 credits

Posts and threads

EndpointMethod and pathCredits
Get a postGET /v1/reddit/posts/{id}2 credits
Get a thread with commentsGET /v1/reddit/threads/{id}3 credits

Subreddits

EndpointMethod and pathCredits
Search subredditsGET /v1/reddit/subreddits/search2 credits
Get a subredditGET /v1/reddit/subreddits/{name}2 credits
List subreddit postsGET /v1/reddit/subreddits/{name}/posts2 credits

Users

EndpointMethod and pathCredits
Get a userGET /v1/reddit/users/{name}up to 3 credits
Get user statusGET /v1/reddit/users/{name}/status2 credits
List user postsGET /v1/reddit/users/{name}/posts2 credits
List user commentsGET /v1/reddit/users/{name}/comments2 credits
Analyse a userGET /v1/reddit/users/{name}/analysisup to 7 credits
Search usersGET /v1/reddit/users/search2 credits

Leads and monitoring

EndpointMethod and pathCredits
Find leadsGET /v1/reddit/leads4 credits
Create a monitorPOST /v1/monitorsPlanned

18+

EndpointMethod and pathCredits
Search 18+ postsGET /v1/reddit/nsfw/search2 credits (18+ setting)
Search 18+ subredditsGET /v1/reddit/nsfw/subreddits/search2 credits (18+ setting)

How Reddit inputs work

InputWhat to passExamples
Post or thread idThe base36 id, the t3_ fullname or the full post URL1g2h3j4, t3_1g2h3j4, https://www.reddit.com/r/SaaS/comments/1g2h3j4/...
SubredditThe name without r/SaaS, smallbusiness
UsernameThe name without u/spez
Search query qReddit search syntax works"exact phrase", crm OR hubspot, crm NOT salesforce, author:name
Time filter timeApplies to search and top feedshour, day, week, month, year, all

Comment trees

reddit.thread returns the post plus a flat list of comments. Rebuild the tree with each comment's parentId. A top-level comment's parent is the post. No Reddit source returns very large threads in full, so compare comments.length with reportedCommentCount and page with cursor for more.

Fields that can be null

Some fields can only be filled from our primary source. When the fallback source serves a call, those fields come back as null and the call still succeeds: subreddit rules and moderators, user bio and badges, and the full text of comments in a user's history (bodyTruncated: true marks a preview). A null means unknown, not empty.

Freshness and caching

Search results are cached for about 10 minutes and subreddit profiles for a day. A cached response says cached: true and costs the same as a fresh one, so repeated calls return the same answer without hitting Reddit again.

Response objects

These are the objects inside data. List endpoints return arrays of them.

RedditPost

FieldTypeNullableDescription
idstringnoPlatform id.
fullnamestringnoReddit fullname (t3_ for posts, t1_ for comments). Dedupe on this.
titlestringnoTitle.
bodystringnoText body. Empty for link and media posts.
authorstringyesAuthor username. Empty (or null) when the account was deleted.
subredditstringnoSubreddit name without r/.
permalinkstringnoPath on reddit.com.
urlstringnoFull URL on the platform.
externalUrlstringyesLink the post points to, when it is a link post.
scorenumberyesScore (upvotes minus downvotes) as Reddit reports it.
numCommentsnumberyesComment count.
upvoteRationumberyesShare of upvotes, 0 to 1.
createdAtstringnoISO 8601 UTC timestamp.
nsfwbooleannoMarked adult content.
lockedbooleanyesComments are locked.
mediaobjectyesImages, video or gallery URLs, or null.

RedditComment

FieldTypeNullableDescription
idstringnoPlatform id.
fullnamestringnoReddit fullname (t3_ for posts, t1_ for comments). Dedupe on this.
parentIdstringyesId of the parent comment or post. Can be a bare id (p9636y0) or a fullname (t1_p9636y0), so strip a t1_ or t3_ prefix before comparing.
postIdstringyesId of the post this comment belongs to.
postTitlestringyesTitle of that post.
authorstringyesAuthor username. Empty (or null) when the account was deleted.
bodystringnoText body. Empty for link and media posts.
bodyTruncatedbooleannoTrue when the text is a preview from a fallback source.
scorenumberyesScore (upvotes minus downvotes) as Reddit reports it.
subredditstringyesSubreddit name without r/.
permalinkstringyesPath on reddit.com.
urlstringyesFull URL on the platform.
createdAtstringnoISO 8601 UTC timestamp.

RedditThread

FieldTypeNullableDescription
postobjectyesThe post, or null when it could not be loaded.
commentsobject[]noFlat list of comments; rebuild the tree with parentId.
unloadedReplyStubsnumbernoReplies Reddit did not load in this page.
reportedCommentCountnumberyesComment count Reddit reports for the post.

Subreddit

FieldTypeNullableDescription
namestringnoName.
titlestringyesTitle.
descriptionstringyesDescription.
subscribersnumberyesSubscriber count.
createdAtstringyesISO 8601 UTC timestamp.
nsfwbooleanyesMarked adult content.
urlstringnoSubreddit URL.
rulesobject[]yesSubreddit rules, or null when the source cannot see them.
moderatorsobject[]yesModerators and since when, or null.
postingobjectyesPosting settings, or null.

RedditUser

FieldTypeNullableDescription
usernamestringnoUsername without u/.
idstringyesPlatform id.
createdAtstringyesISO 8601 UTC timestamp.
karmaobjectnoTotal, post and comment karma.
biostringyesProfile bio.
avatarUrlstringyesAvatar image URL.
badgesobjectyesVerified, employee, moderator and premium flags, or null.

UserStatus

FieldTypeNullableDescription
usernamestringnoUsername without u/.
stateenumnoactive, suspended, not_found_or_banned or unknown.
existsbooleanyesWhether the account exists, null when unknown.

RedditUserAnalysis

FieldTypeNullableDescription
usernamestringnoUsername without u/.
createdAtstringyesWhen the account was created, or null when the profile did not answer.
accountAgeDaysnumberyesWhole days between account creation and now, or null.
karmaobjectnoTotal, post and comment karma.
sampleobjectnoHow big the sample was: posts, comments, their shares, the dates they span, and how many adult items were left out. Every other figure describes this sample, not the whole account.
topSubredditsobject[]noUp to 10 subreddits ranked by sampled posts plus comments: name, posts, comments, items and share of the sample (0 to 1).
activityByHournumber[]no24 counts of sampled posts and comments by UTC hour. Index 0 is 00:00 to 00:59.
activityByWeekdaynumber[]no7 counts of sampled posts and comments by UTC weekday. Index 0 is Monday, index 6 is Sunday.
scoreobjectnoAverage and median score of the sampled posts and comments, and how many had a score.
topPostsobject[]noUp to 3 sampled posts with the highest score.

Lead

FieldTypeNullableDescription
platformenumnoreddit or x.
kindenumnopost, comment or tweet.
idstringnoPlatform id.
urlstringnoFull URL on the platform.
textstringnoText.
authorstringyesAuthor username. Empty (or null) when the account was deleted.
authorUrlstringyesAuthor profile URL.
communitystringyesSubreddit for Reddit items, null for X.
scorenumberyesEngagement score: Reddit upvotes minus downvotes for Reddit items, likes for X items.
createdAtstringyesISO 8601 UTC timestamp.
intentenumnoasking_for_recommendation, comparing_tools, complaining_about_tool or other.
intentScorenumbernoIntent score from 0 to 1.
matchedTermsstring[]noPhrases that made this a lead.

Recipes

Find people asking for a tool like yours

Call /v1/reddit/leads with your category in two or three words and up to five competitors. Results are ranked by intentScore from 0 to 1, and matchedTerms shows the phrases that triggered each one. One page costs 4 credits.

curl "https://api.chatterapi.com/v1/reddit/leads?q=email%20marketing%20tool&competitors=mailchimp,convertkit" \
  -H "Authorization: Bearer $CHATTERAPI_KEY"

Check an account for a shadowban

Call /v1/reddit/users/{name}/status on your own account. If you can log into it but the state is not_found_or_banned, Reddit has hidden it from everyone else. It costs 2 credits, and an account that doesn't exist returns a state rather than an error.

Read a community before posting

Call /v1/reddit/subreddits/{name} for its rules and posting settings, then /v1/reddit/subreddits/{name}/posts?sort=top&time=month to see what the community rewards.

Export a whole thread

Call /v1/reddit/threads/{id} with the post URL and keep passing page.nextCursor as cursor until page.hasMore is false. The Comment Exporter free tool shows the result without code.

Errors you'll see

CodeWhenWhat to do
not_foundThe post, subreddit or user doesn't exist, or the subreddit is private or banned.Check the id or name. Don't retry.
scope_deniedAn 18+ endpoint while 18+ access is off.Turn it on in Settings.
invalid_inputA parameter failed validation. The message names the field.Fix the request.
upstream_errorReddit or both of our sources failed.Retry with backoff. You weren't charged.
insufficient_creditsYour balance is below the call's maximum cost.Top up or wait for your monthly credits.

Every code, with response bodies and what an agent should tell the user, is on Errors.