Search Reddit Comments, Get Real Matches
Genuine Reddit comment search. Returns the actual comments whose body matches your query, with body, score, author and permalink, not the parent posts.
/api/reddit/search/comments/deep$0.02 / callGenuine comment search. Returns the actual comments whose body matches your query, with the comment body, score, author, a comment-deep permalink, and the parent post.
When to use this vs Search Comments
The sibling GET /api/reddit/search/comments is Reddit's native comment-search mode: it matches comment text but hands back the parent posts, never the comments. Use it when you want the threads where a topic is discussed and want the cheapest, fastest call.
This endpoint goes the extra step for you: it takes those parent posts, fetches each post's comment tree, and returns the comments themselves. Use it when you want the first-hand opinions and answers, not just the threads.
How it works
- Runs Reddit's comment search to get the parent posts.
- Fetches each post's comment tree.
- Returns the comments whose visible body contains your query (all terms, at word boundaries; link URLs are ignored), sorted by score.
Because it fans out into several reads, it is a premium call at $0.02 (versus $0.0015 for the plain endpoints). limit bounds how many parent posts it expands into their comment trees, 1-25 (default 5), not how many comments come back.
Going deeper: paginate. The response's after pages the underlying post search, not the comments. Pass it back as after to expand the next batch of parent posts, so you can walk as far as you want while each call stays bounded. Use max_comments to cap how many comments come back (the highest-scored are kept); meta reports comments_matched vs comments_returned vs capped.
Best-effort, not exhaustive. A comment deleted since Reddit indexed it, or one below the fetched tree depth, may be missed. meta.truncated is true when a tree was too deep to walk fully. If you need every comment on a specific thread, fetch it directly with GET /api/reddit/comments.
Partial answers are labelled. Each parent post is its own comment-tree read, and one read can fail while the others succeed. A failed tree is counted, not hidden: meta.partial is true, meta.trees_failed says how many, and meta.trees_fetched how many were read. A parent post that Reddit has removed counts as a failed tree too. The call only fails outright when every tree failed and at least one was refused upstream; then it answers with that read's error and status rather than an empty "no matches".
Each call has a time limit. All reads in one call share a single deadline of about 22 seconds. When it runs low, no further tree is read: the trees already read are returned, the unread ones count in meta.trees_failed, and meta.partial is true. If no tree could be read in time, the call answers 503 with Retry-After and is not billed.
Concurrency
One account can run at most 2 deep comment searches at once. A third waits up
to 3 seconds for a slot, then gets an unbilled 429 with error: "DEEP_SEARCH_CONCURRENCY" and Retry-After: 2. See Rate limits.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Search query. Supports Reddit search syntax. Multi-word requires all terms in the comment. |
limit | number | No | Number of parent posts to expand, 1-25 (default 5). Each is one comment-tree fetch. A value above 25 is clamped (meta.limit_clamped flags it). To go past 25, paginate with after. |
max_comments | number | No | Cap on how many comments are returned (the highest-scored are kept). Omit to return every match. |
after | string | No | Pagination cursor. Pass back the after value from the previous response exactly as issued; it is opaque and carries your paging depth. See Pagination depth. |
sort | string | No | relevance (default), hot, top, new, comments |
t | string | No | Time window: hour, day, week, month, year, all. It bounds the parent posts expanded as well as the comments: a parent post older than the window is not read, and meta.parents_outside_window counts them. With t set, the parent search reads up to 4 pages looking for parents inside the window (meta.parent_pages_read). A page that read no comment tree (meta.trees_fetched 0) and returned no comments is not billed |
nsfw | boolean | No | true to include NSFW results |
group_by | string | No | Set to author for the research mode: return the distinct people who mentioned your query instead of a flat comment list. See Group by author. |
max_authors | number | No | Only with group_by=author. Cap on how many people are returned (the most prolific first). Omit to return everyone. |
Paging past Reddit's cap
Reddit closes a single listing near 1000 items and then stops issuing a
cursor, so listing_status: truncated is Reddit's limit rather than the end of
the data. Every distinct combination of parameters you send is a separate
listing with its own budget, so widen across listings rather than paging
deeper into one.
What you can vary here:
sorttakesrelevance,new,hot,top,comments, each with its own cursor.ttakeshour,day,week,month,year,all. We forward it on every sort.
How far these actually widen has not been measured on this endpoint. On
/api/reddit/posts two sorts ranged from 0 to 99 shared items out of 100
depending on how busy the subreddit was, so read a page of each before
assuming a second sort doubles your coverage.
Example
curl -H "Authorization: Bearer $TOKEN" \
"https://api.redditapis.com/api/reddit/search/comments/deep?q=best%20mechanical%20keyboard&limit=5"const response = await fetch(
"https://api.redditapis.com/api/reddit/search/comments/deep?q=best%20mechanical%20keyboard&limit=5",
{ headers: { Authorization: "Bearer TOKEN" } }
);import requests
response = requests.get(
"https://api.redditapis.com/api/reddit/search/comments/deep",
params={"q": "best mechanical keyboard", "limit": 5},
headers={"Authorization": "Bearer TOKEN"},
)Response Shape
{
"comments": [
{
"id": "t1_n1abc2d",
"body": "The Aula F75 is the best starter board, hands down.",
"score": 42,
"author": "keyboardsage",
"subreddit": "MechKeyboards",
"permalink": "https://reddit.com/r/MechKeyboards/comments/abc123/thread/n1abc2d/",
"parent_id": "t3_abc123",
"is_submitter": false,
"created": "2026-02-02T01:47:30.000Z",
"parent_post": {
"id": "t3_abc123",
"title": "New to mechanical keyboards, what's the best one to get?",
"url": "https://reddit.com/r/MechKeyboards/comments/abc123/thread/"
}
}
],
"after": "t3_abc123",
"meta": {
"posts_scanned": 5,
"limit_used": 5,
"limit_clamped": false,
"comments_matched": 109,
"comments_returned": 25,
"capped": true,
"truncated": false
}
}Response Fields
| Field | Type | Notes |
|---|---|---|
id | string | The t1_ comment fullname |
body | string | The matched comment text |
score | number | null | Comment score. null while the subreddit hides fresh scores or when the score is unknown, never Reddit's placeholder 1 |
author | string | Comment author (no u/ prefix) |
subreddit | string | Subreddit the comment is in |
permalink | string | null | Full URL that deep-links to the comment |
parent_id | string | null | Fullname of what the comment replies to: t1_ for a reply to another comment, t3_ for a top-level comment |
is_submitter | boolean | null | true when the commenter also wrote the post; null when the source did not say |
created | string | null | ISO-8601 timestamp of the comment |
parent_post.id | string | The t3_ fullname of the thread the comment is in |
parent_post.title | string | Thread title |
parent_post.url | string | Thread URL |
after | string | null | Cursor for the next page, or null when there is no next page to request. An empty cursor does not always mean you have every item, so read listing_status (below) to find out which. See Pagination depth. |
meta.posts_scanned | number | How many parent posts were expanded |
meta.limit_used | number | The limit actually applied (1-25) |
meta.limit_clamped | boolean | true if the requested limit was outside 1-25 and was clamped |
meta.comments_matched | number | Total matching comments found (before any max_comments cap) |
meta.comments_returned | number | Comments actually returned (after the cap) |
meta.capped | boolean | true if max_comments trimmed the result |
meta.truncated | boolean | true if any comment tree was too deep to walk fully |
meta.partial | boolean | true if at least one comment-tree read failed, so the result covers fewer parent posts than meta.posts_scanned |
meta.trees_fetched | number | Parent posts whose comment tree was read |
meta.trees_failed | number | Parent posts whose comment tree could not be read (refused upstream, the post was removed, or the call's time limit ran out first) |
meta.window_note | string | Present only when t is set, no comment tree was read and every parent post Reddit matched was older than the window. It says so, so an empty result is not read as "nobody mentioned this". Widen t or page on with after |
meta.t_applied | string | The t window applied to the comments themselves (present when t is set) |
meta.parent_pages_read | number | Pages of the parent search read while looking for parents inside the t window (present when t is set) |
meta.comments_outside_window | number | Matching comments dropped because they are older than the t window |
When after comes back empty
An empty cursor means there is no next page to ask for. It does not always mean
you have every comment: Reddit often stops serving a busy listing long before it
runs out. Paging r/all on 2026-08-14 stopped after 400 posts covering about a
minute of a feed that plainly holds more.
The response tells you which happened. When after is null it also carries
listing_status, which reads complete, truncated or unknown. Only
complete means you have everything; treat the other two as a partial answer
and widen your search rather than stopping. The full field list and what to do
about each answer is in Pagination depth.
Group by author (research mode)
Pass group_by=author when you want to know who is talking about a topic rather than reading every comment. Instead of a flat comments array, the response returns an authors array: the distinct people whose comments matched, ranked by how many of their comments matched (then by total score). Each author carries their matching-comment count, total score, the subreddits they matched in, and their single top comment. Use max_authors to cap the number of people returned (the most prolific first). Removed accounts (Reddit's [deleted]) are dropped so they never collapse into one fake mega-author.
curl -H "Authorization: Bearer $TOKEN" \
"https://api.redditapis.com/api/reddit/search/comments/deep?q=best%20mechanical%20keyboard&group_by=author&max_authors=20"{
"authors": [
{
"author": "keyboardsage",
"comment_count": 4,
"total_score": 118,
"subreddits": ["MechanicalKeyboards", "MechKeyboards"],
"top_comment": {
"body": "The Aula F75 is the best starter board, hands down.",
"score": 42,
"permalink": "https://reddit.com/r/MechKeyboards/comments/abc123/thread/n1abc2d/",
"subreddit": "MechKeyboards"
}
}
],
"after": "t3_abc123",
"meta": {
"group_by": "author",
"posts_scanned": 5,
"limit_used": 5,
"limit_clamped": false,
"comments_matched": 109,
"authors_matched": 37,
"authors_returned": 20,
"authors_capped": true,
"truncated": false
}
}| Field | Type | Notes |
|---|---|---|
authors[].author | string | The redditor's username (no u/ prefix) |
authors[].comment_count | number | How many of their comments matched the query |
authors[].total_score | number | Sum of those comments' scores (a rough reach signal) |
authors[].subreddits | string[] | Distinct subreddits they matched in (sorted) |
authors[].top_comment | object | Their highest-scored matching comment (body, score, permalink, subreddit) |
meta.authors_matched | number | Distinct people found (before any max_authors cap) |
meta.authors_returned | number | People actually returned (after the cap) |
meta.authors_capped | boolean | true if max_authors trimmed the people list |
Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.
Search Comments
Search Reddit by comment text. Reddit matches your keyword against comments and returns the parent posts, surfacing threads plain title search misses.
Search Communities
Search subreddits by name or topic, the Communities tab on reddit.com. Verified to match Reddit's UI rank order for SFW and NSFW queries, with pagination.
