Reddit API documentation: the complete 2026 guide

Last updated August 2026 Our platform serves 74 REST endpoints, per our published API reference, and this guide walks all of them.

Every way to access the Reddit API

There is no single Reddit API. There are five practical routes to Reddit data, and they differ on authentication, rate limits, price, and whether they allow writes. The table lays them side by side so you can pick the one that fits your project before you write a line of code.

PRAW, the .json endpoints, and third-party scrapers all inherit Reddit's OAuth limits or its terms of service, and Pushshift, the historical archive many teams relied on, is now restricted to Reddit moderators. If you need a drop-in that skips the OAuth handshake, the app-review queue, and the per-minute cap, a hosted per-call API is the shortest path. For a deeper look at each route, see the PRAW alternative, the Pushshift alternative, the Reddit scraper API, and the cheapest Reddit API breakdowns. Curious what teams build once they have access? The use-cases page walks through trend spotting, brand monitoring, and product research.

Choosing between those five routes is easier with the numbers side by side. There is a latency, uptime and cost benchmark across providers, a head-to-head with Scrapingdog, a look at where no-code automation tools stop being enough, and a walkthrough of Arctic Shift as an archive source for AI agents. Before any of them goes into production, the commercial-use and licensing rules decide what you are allowed to do with the data at all, which is the question that most often gets asked last and should be asked first.

Quick reference

Authentication

Every request carries your key in one header. There is no OAuth token exchange, no refresh cycle, and no app-review step. Generate a key on the Reddit API key page, then send it as a bearer token:

Authorization: Bearer YOUR_REDDITAPIS_KEY

The same token works for reads, votes, writes, and direct messages, so there is a single credential to manage. For the exact header and a working request, see how to authenticate the Reddit API.

Your first request

The most common call reads a subreddit feed. Here is the same request in three languages, each returning clean JSON you can parse immediately.

curl

curl -X GET \
  -H "Authorization: Bearer $REDDITAPIS_KEY" \
  "https://api.redditapis.com/api/reddit/posts?subreddit=programming&sort=new&limit=25"

Python

import os, requests

res = requests.get(
    "https://api.redditapis.com/api/reddit/posts",
    params={"subreddit": "programming", "sort": "new", "limit": 25},
    headers={"Authorization": f"Bearer {os.getenv('REDDITAPIS_KEY')}"},
)
posts = res.json()

Node.js

const url = "https://api.redditapis.com/api/reddit/posts?subreddit=programming&sort=new&limit=25";
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.REDDITAPIS_KEY}` },
});
const posts = await res.json();

Full language walkthroughs live in the Python and Node.js answers. If your stack is neither, there are runnable clients for Go using nothing but net/http, and for Bun on its native fetch.

The endpoint catalog

Redditapis exposes 74 endpoints. The read tier holds 38 routes; the eleven listed below are the ones most projects call, and the tier also covers single comment lookups, the full comment tree under a post, and a batch comment-verify route. Reads are $0.0015 each.

Several of these routes have a walkthrough of their own, with the response shape and the edge cases the table has no room for: user profiles, karma and history, images, videos and galleries, posting rules as JSON, moderators and the wiki, and hydrating many posts in one call instead of one request each.

The remaining tiers cover deep comment search, voting, writes, and direct messages. Prices rise with the action, since a write costs Reddit more than a read. Deep comment search is the one worth reading before you budget for it, since it is the route people reach for after Pushshift, and Reddit's own DM caps bound the messaging tier regardless of what you are willing to spend.

8 free account reads, 3 free feedback endpoints and11 plan-billed monitoring endpoints round out the 74: your own account details and payment history, a bug or feature report to the team and its status, and keyword monitors. For the count and the reasoning behind it, see how many Reddit API endpoints there are.

Pagination

Listing endpoints return results in pages. Each response includes an after token; pass it as a query parameter on the next request to pull the following page, and stop when the token comes back empty. That loop is how you pull a whole subreddit or a full comment history without hitting a single oversized response.

Three details save debugging time. The after value is an opaque cursor we issue, so pass it back unchanged rather than building one from a Reddit fullname. Ask for the largest page, a limit of 100, because a read costs $0.0015 whatever it returns. And expect Reddit's own ceiling: any single listing stops at roughly 1,000 posts, whichever API reads it, so to go further back you page through several sort orders, such as new and top by timeframe, each with its own cursor, or switch to search.

Searching Reddit

Search is split by what you want back, so a query for communities never returns posts you have to filter out. /api/reddit/search searches posts sitewide or, with a subreddit parameter, inside one community. Separate endpoints search comments, communities, media posts and users. Each is a $0.0015read except deep comment search, /api/reddit/search/comments/deep, which is $0.02because one call runs a comment search and then reads the comment tree of each matching parent post for you, 5 by default and up to 25 with the limit parameter. At most 2 deep searches can run at once per account. Use the plain comment search to find where a phrase appears, and the deep one when you need the surrounding conversation in the same response.

Working with comments

A post's comment tree comes from /api/reddit/post/{id}/comments, or from/api/reddit/comments with a permalink when that is what you have. A single comment is/api/reddit/comment/{id}, and /api/reddit/sub/{name}/comments returns the newest comments across a whole subreddit, which is the cheapest way to watch a community's discussion without reading every thread. To check whether comments you placed or are tracking still exist,POST /api/reddit/comments/verify takes up to 100 comment ids and reports each as live, deleted, removed or not found, billed as one read at any batch size.

Accessing subreddits

A subreddit is more than its post feed, and the API breaks it into eight routes so you fetch only the slice you need. The listing and top-post routes return submissions, the comments route streams the newest comments across the whole community, and the about, rules, moderators, and wiki routes return the metadata you need before you read or write there. A discovery route finds communities by keyword. Every one is a $0.0015 read.

Reading the rules route before you post is the cheapest insurance against a removed submission, since it returns the same rules a moderator enforces. The newest-comments route is the cheapest way to watch a community's discussion without reading each thread one at a time.

Writing to Reddit: login, comments, votes and DMs

Writes act as a real Reddit account, so they start with POST /api/reddit/login, which returns a session for that account. With the session you can create a post, comment or reply, update the profile bio, display name or avatar, vote, and send or read direct messages. Writes are $0.012 a call, a vote is $0.005 and a DM is $0.025, priced above reads because each one runs through an authenticated session rather than a public read.

The API does not change Reddit's rules about what an account may post. Read a community's rules first, which /api/reddit/sub/{name}/rules returns as structured data, and pace writes the way a person would. Accounts that post too fast or too promotionally get filtered by Reddit and by moderators no matter how the request was sent.

Monitoring and webhooks

The 11 monitoring endpoints manage keyword monitors instead of reading Reddit directly. You create a monitor for a keyword, either across all of Reddit or inside named subreddits, register a webhook, and matches are pushed to you as they appear. Webhook deliveries are HMAC-signed so you can verify they came from us, and failed deliveries are retried for up to 21 minutes. A test endpoint sends a sample delivery so you can check your receiver before a real match arrives, and Slack and Discord work as delivery targets too.

These calls are free per request because monitoring is billed by plan rather than per call, so a monitor that fires a thousand times does not bill a thousand times. Plans and check intervals are on thepricing page, and the product itself is described on theReddit monitoring APIpage.

Using the API from an AI agent

The published MCP server, redditapis-mcp on npm, exposes the read endpoints as tools for Claude, Cursor and any other MCP client. Run it with npx, set REDDITAPIS_KEY to your key, and the agent can search Reddit, read posts and comment trees, and look up users and communities without HTTP code. It also carries the free monitor and feedback tools. Writes, votes and DMs are not on the MCP tool surface: they stay REST calls your own code makes, so a model choosing tools cannot post or vote on its own. Install steps for each client are on theReddit MCP serverpage.

Sentiment analysis with Reddit comments

Sentiment work is a common reason teams pull Reddit data, and the API gives you the input rather than the verdict. Collect the raw text with comment search or deep comment search, which returns the full comment body, author, score, and permalink as JSON, then feed that text to your own sentiment model or a hosted LLM for scoring. We run no sentiment step ourselves, so the tone, the model, and the labels stay entirely yours.

Two practical notes. Score comments rather than only post titles, since the opinion usually lives in the replies, and deep comment search at $0.02 pulls the surrounding conversation in one call so you are scoring a thread, not a line. Keep each comment's permalink and id with its score, so you can re-check later whether a comment was edited or deleted before you report on a trend. The use-cases page walks through brand and topic sentiment end to end.

A short checklist before you go to production

• Keep the key in an environment variable or a secret store, never in client-side code. Anyone holding it can spend your balance.
• Request full pages, a limit of 100, on any listing you are going to page through. A read costs $0.0015whatever it returns.
• Store the newest post or comment id you have processed and stop paging when you reach it, so routine polls cost one read instead of a re-crawl.
• Back off and retry on a 429 or 503, treat a 402 as a signal to top up, and alert on it rather than letting a scheduled job fail quietly.
• Log the X-Credits-Remaining header that comes back on every successful response, and stop a large job before the balance runs out rather than halfway through.
• For writes, read the community's rules first and pace posting the way a person would. The API does not exempt an account from Reddit's spam filters or a moderator's judgement.
• Keep permalinks with anything you store, so every record can be traced back to its source thread later.
• Run the job once against a single small subreddit before pointing it at the full list. A dry run on real data catches a wrong sort, a missing cursor or a field name typo for the price of a few reads, instead of after a large backfill has already spent the budget.

Best practices and considerations

Reddit data is public, but public does not mean unconstrained, and a few considerations keep a project on the right side of both Reddit and the people whose posts you read. The three that matter most are user privacy, honoring deletions, and staying inside Reddit's terms. None of them is optional for anything you ship, and all three are easier to build in from the start than to retrofit later.

Privacy and personal data

A username is an identifier, and comment history can be personal. Store only what your use case needs, avoid building profiles that single out a private individual, and keep permalinks so a record can always be traced back to its source rather than detached from its context.

Deletions and removals

Content that a user deletes or a moderator removes should not live on in your dataset. The batch comment-verify route takes up to 100 ids and reports each as live, deleted, removed, or not found for the price of one read, so you can re-check stored content on a schedule and drop anything that is gone before you analyze or publish it.

Terms of service and content policy

Reddit's Data API Terms and content policy govern what you may do with the data regardless of how you fetch it, and commercial use in particular has its own rules. What the Responsible Builder Policy, in force since 11 November 2025, allows and denies is laid out on the Responsible Builder Policy page, and the commercial-use and licensing guide covers the rest.

Rate limits

Redditapis meters by spend, and each key gets a burst of about 20 calls, then a steady pace of about10 reads a second; a call over the pace gets a short wait instead of an error. A 503 means upstream capacity is briefly saturated. A 429 has four causes: a call over its key's pace that would wait more than 10 seconds, upstream capacity pushing back, a third deep comment search while 2 are still running on your account, or Reddit throttling the account session behind an authenticated read (home feed, private listings). Each 429 carries a Retry-After header, and the fix is to wait that long and retry. Reddit throttling a write comes back as a 5xx error (usually a 502) instead, not a 429, with code REDDIT_RATELIMIT when you create posts too fast. The official Reddit Data API, by contrast, caps the free OAuth tier near 100 queries per minute. The full breakdown, including how to avoid PRAW throttling, is on the rate limits answer. Two failure modes are worth recognising on sight because neither is really a rate limit: the "your request has been rate limited" page Reddit serves to logged-out traffic, and a job that works locally and dies in GitHub Actions, which is a datacentre-IP block wearing a 429's clothes.

Status codes and error handling

Pricing per call

Billing is usage-based, so you pay per call rather than for a monthly seat. A project that mostly reads posts and comments pays cents for thousands of calls, and the $0.50 in signup credits covers about 333 reads.

Run your own volume on the cost calculator, or read the full breakdown on the pricing page.

How this differs from the official Reddit API docs

Reddit maintains its own documentation at developers.reddit.com for the OAuth Data API. That path is free for personal, non-commercial use, but commercial access is sold by negotiated agreement at a reported $0.24 per 1,000 calls, which is $0.00024 per call, behind an app-review queue. The $12,000 figure widely quoted since 2023 is that same rate at 50 million requests, not a separate annual fee. Redditapis is a REST wrapper: one bearer token, no review, and flat per-call pricing from $0.0015. Commercial keys on the official path also wait on manual app review before they go live, whereas a Redditapis key works the moment you generate it. Use the official docs when you need first-party OAuth scopes; use this guide when you want data in minutes without a contract. The side-by-side comparison is on the Redditapis versus official Reddit API page, and the official reference is at developers.reddit.com.

Getting official access from Reddit

If you take the first-party route instead of a hosted API, access to Reddit's own Data API comes in three steps: register a developer app, authenticate over OAuth and agree to the Data API Terms, then, for anything commercial, apply for commercial access and comply with the Responsible Builder Policy before your keys go live. Here is what each step involves and where the waits are.

Step 1. Register a developer app

Create an app at reddit.com/prefs/apps to get a client id and secret. You choose the app type (script, web, or installed), set a redirect URI, and name the app. These credentials identify your client to Reddit on every OAuth request that follows.

Step 2. Authenticate over OAuth and accept the Data API Terms

Exchange those credentials for an OAuth access token, refresh it as it expires, and send it on every call. Free access is licensed for personal, non-commercial use at roughly 100 queries per minute per OAuth client, and using it binds you to Reddit's Data API Terms.

Step 3. Apply for commercial access under the Responsible Builder Policy

Commercial use is sold by agreement at a reported $0.24 per 1,000 calls and sits behind an app-review queue, so the keys are not instant. Reddit's Responsible Builder Policy, in force since 11 November 2025, sets what a builder may and may not do with the data; what it allows and denies is detailed on the Responsible Builder Policy page. Redditapis skips registration, OAuth, and the review queue: one bearer token works the moment you generate it.

Frequently asked