Reddit Search API: How to Search Reddit Posts and Comments from Code

The Reddit search API lets you search Reddit posts from code: one endpoint for all of Reddit, the same endpoint scoped to a subreddit, and a separate one for finding subreddits. This guide covers the parameters, what comes back, the search operators, a minimal Python example and the limits you will hit. Then it covers the part the official API does not do well: searching comments, and searching at scale or on a schedule.

Reddit’s live API reference at reddit.com/dev/api is only partly readable to automated tools, so the parameter details below come from the code Reddit published in its open-source repository, which generates that reference. The repository is archived, so Reddit may have changed details since. Test your exact calls before you depend on them.

The Reddit search API endpoints

Endpoint	What it searches
GET /search	Posts across all of Reddit
GET /r/<subreddit>/search with restrict_sr=1	Posts in one subreddit
GET /subreddits/search	Subreddits, by title and description

All three need an OAuth token with the read scope and go to https://oauth.reddit.com. Setting up the app and token is covered in our guide on how to get a Reddit API key.

One detail trips people up. In the search controller, restrict_sr defaults to false. If you call /r/python/search without restrict_sr=1, the search runs across all of Reddit, not just r/python.

Search parameters

Parameter	Values	Notes
q	Your query, up to 512 characters	Supports field operators (see below)
sort	relevance, hot, top, new, comments	Default relevance. comments sorts by comment count.
t	hour, day, week, month, year, all	Time range. Default all.
restrict_sr	1 or 0	Limit to the subreddit in the path
limit	1 to 100	Results per page. Default 25.
after / before	A fullname such as t3_abc123	Cursor for the next or previous page
type	link, sr	Result types. The API defaults to link (posts).

The limit range comes from the shared listing validator, and the sort and time values from Reddit’s menu definitions.

What the Reddit search API returns

A search returns a Listing. Its data.children array holds posts of kind t3, each with fields such as title, selftext, author, subreddit, score, num_comments, created_utc, permalink and url. data.after holds the cursor for the next page, and it is null when there are no more results. Comments are not included: you request them separately per post at /comments/<post id>.

/subreddits/search returns subreddits instead of posts, matched on title and description. It takes the same q, limit and after parameters. Use it first when you don’t yet know which communities talk about your topic, then run post searches with restrict_sr=1 inside the best matches. Because each query pages through a limited listing, that two-step approach can also give you more results in total than one broad search across all of Reddit.

Search operators that work

Reddit’s current help page on search operators refused our automated request, so we cannot quote it. Reddit’s search index code shows which post fields are indexed, and these are the operators built on them:

Operator	Example	Finds
author:	author:spez	Posts by one user
subreddit:	subreddit:python asyncio	Posts in one subreddit
title:	title:"rate limit"	Words in the title only
selftext:	selftext:refund	Words in the post body
self:	self:yes	Text posts only (self:no for link posts)
site:	site:github.com	Link posts to a domain
url:	url:youtube	Words in the linked URL
flair:	flair:question	Posts with a flair
nsfw:	nsfw:no	Excludes adult posts

Combine them with plain words, quotes for phrases, and AND, OR and NOT. Because the source is archived code, check each operator against reddit.com search before you rely on it.

Minimal Python example

This example uses requests and an app-only token. It searches r/python for posts about asyncio from the past month, newest first, and follows the after cursor for up to three pages.

import os
import requests

USER_AGENT = "script:my-search-app:v0.1 (by /u/your_username)"

token = requests.post(
    "https://www.reddit.com/api/v1/access_token",
    auth=(os.environ["REDDIT_CLIENT_ID"], os.environ["REDDIT_CLIENT_SECRET"]),
    data={"grant_type": "client_credentials"},
    headers={"User-Agent": USER_AGENT},
    timeout=30,
).json()["access_token"]

headers = {"Authorization": f"bearer {token}", "User-Agent": USER_AGENT}
params = {"q": "asyncio", "restrict_sr": 1, "sort": "new", "t": "month", "limit": 100}
after = None

for page in range(3):
    if after:
        params["after"] = after
    resp = requests.get("https://oauth.reddit.com/r/python/search",
                        headers=headers, params=params, timeout=30)
    resp.raise_for_status()
    data = resp.json()["data"]
    for child in data["children"]:
        post = child["data"]
        print(post["created_utc"], post["num_comments"], post["title"])
    after = data["after"]
    if not after:
        break

If you prefer a Python Reddit API wrapper, PRAW wraps the same endpoint as reddit.subreddit("python").search("asyncio", sort="new", time_filter="month"). A wrapper does not lift Reddit’s rate limits, so the limits below still apply.

Common problems with Reddit search

Results are capped

You get at most 100 results per request, and paging with after does not go on forever. Reddit does not document a total cap per query in the pages we could read, but listings end after a limited number of pages. If you need more, split the search: by subreddit, by time range with t, by sort (new, top and comments surface different posts), or into narrower queries.

No full-text comment search

The documented type parameter accepts only link and sr. There is no comment result type in the API, and the indexed fields belong to posts and subreddits. To find comments that mention a word, you have to search for matching posts, download each comment thread and filter it yourself. For 50 posts that is 50 extra requests.

Rate limits

Reddit’s free limit is 100 queries per minute per OAuth client ID with OAuth and 10 without, effective July 1, 2023 (Key Facts). Each response carries X-Ratelimit-Used, X-Ratelimit-Remaining and X-Ratelimit-Reset headers (API rules). Use a unique User-Agent: generic ones like “Python/urllib” are “drastically limited.” Fetching comment threads for many search results is what usually pushes a script into 429 errors. For what happens beyond the free tier, see Reddit API pricing.

Relevance changes between runs

With sort=relevance, the same query can return a different order on different days. For monitoring, use sort=new and keep track of the post IDs you have already seen.

Searching Reddit posts and comments at scale

The official API is the right choice when you also post, vote, moderate or act for a logged-in user, or when you need a formal licence from Reddit. Our tools only read public data and cannot do any of that.

If you only need to read, our Reddit Actors handle the search, paging, comment threads and filtering for you. They run on Apify and need an Apify account, but no Reddit app and no Reddit API key:

• Reddit Scraper searches all of Reddit or one subreddit, with Relevance, New, Top or Most comments sort and a time range. It returns up to 10,000 posts per search and, with comments turned on, full threads with depth and parent, up to 10,000 comments per post.
• Reddit Comments Scraper finds posts for your keywords, then scrapes their comments. Its “only comments containing” filter is the closest thing to comment search, and comments skipped by your filters are not charged.
• Reddit Keyword Monitor is for ongoing keyword alerts. Each run returns only new posts that mention your keywords, with where it matched and a snippet. Schedule it daily and send results to Slack, email or a spreadsheet.

Store prices on the day we wrote this, per 1,000 results:

Actor	Free plan	Starter	Scale	Business
Reddit Scraper (posts or comments)	$1.50	$1.20	$1.10	$1.00
Reddit Comments Scraper (comments)	$1.50	$1.20	$1.10	$1.00
Reddit Keyword Monitor (mentions)	$3.50	$2.40	$2.35	$2.30

Each run also has a start fee of $0.05 per 1,000 runs per GB of memory. The cards below show current prices.

Which route to pick

1. A few searches a day inside a non-commercial app: the official search API, with the Python example above.
2. Searching comments for a word: the Reddit Comments Scraper, or your own code that downloads and filters threads.
3. Daily alerts for a brand or keyword: the Reddit Keyword Monitor on a schedule.
4. Large exports of posts and threads for research: the Reddit Scraper.

Whichever you choose, follow Reddit’s terms and data protection law, and treat usernames as personal data.