RedditapisRedditapis
Search by Type

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.

GET/api/reddit/search/comments/deep$0.02 / call

Genuine 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

  1. Runs Reddit's comment search to get the parent posts.
  2. Fetches each post's comment tree.
  3. 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

ParameterTypeRequiredDescription
qstringYesSearch query. Supports Reddit search syntax. Multi-word requires all terms in the comment.
limitnumberNoNumber 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_commentsnumberNoCap on how many comments are returned (the highest-scored are kept). Omit to return every match.
afterstringNoPagination cursor. Pass back the after value from the previous response exactly as issued; it is opaque and carries your paging depth. See Pagination depth.
sortstringNorelevance (default), hot, top, new, comments
tstringNoTime 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
nsfwbooleanNotrue to include NSFW results
group_bystringNoSet 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_authorsnumberNoOnly 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:

  • sort takes relevance, new, hot, top, comments, each with its own cursor.
  • t takes hour, 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

FieldTypeNotes
idstringThe t1_ comment fullname
bodystringThe matched comment text
scorenumber | nullComment score. null while the subreddit hides fresh scores or when the score is unknown, never Reddit's placeholder 1
authorstringComment author (no u/ prefix)
subredditstringSubreddit the comment is in
permalinkstring | nullFull URL that deep-links to the comment
parent_idstring | nullFullname of what the comment replies to: t1_ for a reply to another comment, t3_ for a top-level comment
is_submitterboolean | nulltrue when the commenter also wrote the post; null when the source did not say
createdstring | nullISO-8601 timestamp of the comment
parent_post.idstringThe t3_ fullname of the thread the comment is in
parent_post.titlestringThread title
parent_post.urlstringThread URL
afterstring | nullCursor 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_scannednumberHow many parent posts were expanded
meta.limit_usednumberThe limit actually applied (1-25)
meta.limit_clampedbooleantrue if the requested limit was outside 1-25 and was clamped
meta.comments_matchednumberTotal matching comments found (before any max_comments cap)
meta.comments_returnednumberComments actually returned (after the cap)
meta.cappedbooleantrue if max_comments trimmed the result
meta.truncatedbooleantrue if any comment tree was too deep to walk fully
meta.partialbooleantrue if at least one comment-tree read failed, so the result covers fewer parent posts than meta.posts_scanned
meta.trees_fetchednumberParent posts whose comment tree was read
meta.trees_failednumberParent 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_notestringPresent 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_appliedstringThe t window applied to the comments themselves (present when t is set)
meta.parent_pages_readnumberPages of the parent search read while looking for parents inside the t window (present when t is set)
meta.comments_outside_windownumberMatching 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
  }
}
FieldTypeNotes
authors[].authorstringThe redditor's username (no u/ prefix)
authors[].comment_countnumberHow many of their comments matched the query
authors[].total_scorenumberSum of those comments' scores (a rough reach signal)
authors[].subredditsstring[]Distinct subreddits they matched in (sorted)
authors[].top_commentobjectTheir highest-scored matching comment (body, score, permalink, subreddit)
meta.authors_matchednumberDistinct people found (before any max_authors cap)
meta.authors_returnednumberPeople actually returned (after the cap)
meta.authors_cappedbooleantrue 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.

On this page