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,pageon list endpoints,credits,requestIdandcached. 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.searchis thereddit_searchtool. - 18+ tools (
/v1/reddit/nsfw/...) only answer once the account owner turns on 18+ access in Settings. Until then they returnscope_denied.
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.
Search
| Endpoint | Method and path | Credits |
|---|---|---|
| Search posts | GET /v1/reddit/search | 2 credits |
| Search comments | GET /v1/reddit/comments/search | 2 credits |
| Search media | GET /v1/reddit/media/search | 2 credits |
Posts and threads
| Endpoint | Method and path | Credits |
|---|---|---|
| Get a post | GET /v1/reddit/posts/{id} | 2 credits |
| Get a thread with comments | GET /v1/reddit/threads/{id} | 3 credits |
Subreddits
| Endpoint | Method and path | Credits |
|---|---|---|
| Search subreddits | GET /v1/reddit/subreddits/search | 2 credits |
| Get a subreddit | GET /v1/reddit/subreddits/{name} | 2 credits |
| List subreddit posts | GET /v1/reddit/subreddits/{name}/posts | 2 credits |
Users
| Endpoint | Method and path | Credits |
|---|---|---|
| Get a user | GET /v1/reddit/users/{name} | up to 3 credits |
| Get user status | GET /v1/reddit/users/{name}/status | 2 credits |
| List user posts | GET /v1/reddit/users/{name}/posts | 2 credits |
| List user comments | GET /v1/reddit/users/{name}/comments | 2 credits |
| Analyse a user | GET /v1/reddit/users/{name}/analysis | up to 7 credits |
| Search users | GET /v1/reddit/users/search | 2 credits |
Leads and monitoring
| Endpoint | Method and path | Credits |
|---|---|---|
| Find leads | GET /v1/reddit/leads | 4 credits |
| Create a monitor | POST /v1/monitors | Planned |
18+
| Endpoint | Method and path | Credits |
|---|---|---|
| Search 18+ posts | GET /v1/reddit/nsfw/search | 2 credits (18+ setting) |
| Search 18+ subreddits | GET /v1/reddit/nsfw/subreddits/search | 2 credits (18+ setting) |
How Reddit inputs work
| Input | What to pass | Examples |
|---|---|---|
| Post or thread id | The base36 id, the t3_ fullname or the full post URL | 1g2h3j4, t3_1g2h3j4, https://www.reddit.com/r/SaaS/comments/1g2h3j4/... |
| Subreddit | The name without r/ | SaaS, smallbusiness |
| Username | The name without u/ | spez |
Search query q | Reddit search syntax works | "exact phrase", crm OR hubspot, crm NOT salesforce, author:name |
Time filter time | Applies to search and top feeds | hour, 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
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | Platform id. |
fullname | string | no | Reddit fullname (t3_ for posts, t1_ for comments). Dedupe on this. |
title | string | no | Title. |
body | string | no | Text body. Empty for link and media posts. |
author | string | yes | Author username. Empty (or null) when the account was deleted. |
subreddit | string | no | Subreddit name without r/. |
permalink | string | no | Path on reddit.com. |
url | string | no | Full URL on the platform. |
externalUrl | string | yes | Link the post points to, when it is a link post. |
score | number | yes | Score (upvotes minus downvotes) as Reddit reports it. |
numComments | number | yes | Comment count. |
upvoteRatio | number | yes | Share of upvotes, 0 to 1. |
createdAt | string | no | ISO 8601 UTC timestamp. |
nsfw | boolean | no | Marked adult content. |
locked | boolean | yes | Comments are locked. |
media | object | yes | Images, video or gallery URLs, or null. |
RedditComment
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | no | Platform id. |
fullname | string | no | Reddit fullname (t3_ for posts, t1_ for comments). Dedupe on this. |
parentId | string | yes | Id 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. |
postId | string | yes | Id of the post this comment belongs to. |
postTitle | string | yes | Title of that post. |
author | string | yes | Author username. Empty (or null) when the account was deleted. |
body | string | no | Text body. Empty for link and media posts. |
bodyTruncated | boolean | no | True when the text is a preview from a fallback source. |
score | number | yes | Score (upvotes minus downvotes) as Reddit reports it. |
subreddit | string | yes | Subreddit name without r/. |
permalink | string | yes | Path on reddit.com. |
url | string | yes | Full URL on the platform. |
createdAt | string | no | ISO 8601 UTC timestamp. |
RedditThread
| Field | Type | Nullable | Description |
|---|---|---|---|
post | object | yes | The post, or null when it could not be loaded. |
comments | object[] | no | Flat list of comments; rebuild the tree with parentId. |
unloadedReplyStubs | number | no | Replies Reddit did not load in this page. |
reportedCommentCount | number | yes | Comment count Reddit reports for the post. |
Subreddit
| Field | Type | Nullable | Description |
|---|---|---|---|
name | string | no | Name. |
title | string | yes | Title. |
description | string | yes | Description. |
subscribers | number | yes | Subscriber count. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
nsfw | boolean | yes | Marked adult content. |
url | string | no | Subreddit URL. |
rules | object[] | yes | Subreddit rules, or null when the source cannot see them. |
moderators | object[] | yes | Moderators and since when, or null. |
posting | object | yes | Posting settings, or null. |
RedditUser
| Field | Type | Nullable | Description |
|---|---|---|---|
username | string | no | Username without u/. |
id | string | yes | Platform id. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
karma | object | no | Total, post and comment karma. |
bio | string | yes | Profile bio. |
avatarUrl | string | yes | Avatar image URL. |
badges | object | yes | Verified, employee, moderator and premium flags, or null. |
UserStatus
| Field | Type | Nullable | Description |
|---|---|---|---|
username | string | no | Username without u/. |
state | enum | no | active, suspended, not_found_or_banned or unknown. |
exists | boolean | yes | Whether the account exists, null when unknown. |
RedditUserAnalysis
| Field | Type | Nullable | Description |
|---|---|---|---|
username | string | no | Username without u/. |
createdAt | string | yes | When the account was created, or null when the profile did not answer. |
accountAgeDays | number | yes | Whole days between account creation and now, or null. |
karma | object | no | Total, post and comment karma. |
sample | object | no | How 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. |
topSubreddits | object[] | no | Up to 10 subreddits ranked by sampled posts plus comments: name, posts, comments, items and share of the sample (0 to 1). |
activityByHour | number[] | no | 24 counts of sampled posts and comments by UTC hour. Index 0 is 00:00 to 00:59. |
activityByWeekday | number[] | no | 7 counts of sampled posts and comments by UTC weekday. Index 0 is Monday, index 6 is Sunday. |
score | object | no | Average and median score of the sampled posts and comments, and how many had a score. |
topPosts | object[] | no | Up to 3 sampled posts with the highest score. |
Lead
| Field | Type | Nullable | Description |
|---|---|---|---|
platform | enum | no | reddit or x. |
kind | enum | no | post, comment or tweet. |
id | string | no | Platform id. |
url | string | no | Full URL on the platform. |
text | string | no | Text. |
author | string | yes | Author username. Empty (or null) when the account was deleted. |
authorUrl | string | yes | Author profile URL. |
community | string | yes | Subreddit for Reddit items, null for X. |
score | number | yes | Engagement score: Reddit upvotes minus downvotes for Reddit items, likes for X items. |
createdAt | string | yes | ISO 8601 UTC timestamp. |
intent | enum | no | asking_for_recommendation, comparing_tools, complaining_about_tool or other. |
intentScore | number | no | Intent score from 0 to 1. |
matchedTerms | string[] | no | Phrases 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
| Code | When | What to do |
|---|---|---|
not_found | The post, subreddit or user doesn't exist, or the subreddit is private or banned. | Check the id or name. Don't retry. |
scope_denied | An 18+ endpoint while 18+ access is off. | Turn it on in Settings. |
invalid_input | A parameter failed validation. The message names the field. | Fix the request. |
upstream_error | Reddit or both of our sources failed. | Retry with backoff. You weren't charged. |
insufficient_credits | Your 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.