Reddit Search API

What is the Reddit Search API?

Pass a keyword and get matching public posts across Reddit as clean JSON. Sort with sort=relevance|new|top|hot|comments (alias comment_count); for top/comments use timeframe=hour|day|week|month|year|all (default all). The response echoes sort and timeframe. Each result includes id/name (t3_…), title, text, subreddit, author + authorFullname (t2_…), Reddit's authoritative score (not ups−downs), upvotes/downs/upvoteRatio, scoreHidden when Reddit hides the score, comments, subscriberCount, totalAwardsReceived, isVideo, ISO publishedAt, flair, nsfw, and thumbnail. Cursor pagination via nextCursor/hasMore. This endpoint returns posts only — not a comments[] or media[] search surface. Flat 2 credits. Pass cache=true for the 24h shared cache.

What you get

• sort + timeframe echo (relevance/new/top/hot/comments × hour…all)
• authorFullname (t2_…) + authoritative score + upvoteRatio + scoreHidden
• isVideo + totalAwardsReceived; flair/nsfw/thumbnail; subscriberCount
• Cursor pagination (nextCursor + hasMore); ISO publishedAt

Platform limits

Honest ceilings from the upstream platform surface — not Captapi bugs. Unexpected truncation here is usually the platform, not us.

• Posts only (kind=t3). ScrapeCreators returns posts + comments[] + media[] from a richer search surface — comment brand listening needs a separate comments path (not this endpoint).
• Public JSON almost always zeros downs. New posts with hide_score can show score/upvotes 0 while upvoteRatio is still set — use scoreHidden and do not treat score 0 as worthless until the hide window ends.

Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).

curl "https://api.captapi.com/v1/reddit/search?q=james%20webb" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

Example response

{
  "success": true,
  "data": {
    "query": "james webb",
    "sort": "relevance",
    "timeframe": null,
    "totalReturned": 5,
    "nextCursor": "t3_1s1neio",
    "hasMore": true,
    "results": [
      {
        "platform": "reddit",
        "id": "1rh4u8o",
        "name": "t3_1rh4u8o",
        "url": "https://www.reddit.com/r/todayilearned/comments/1rh4u8o/til_the_james_webb_space_telescope_has_found_over/",
        "title": "TIL the James Webb Space Telescope has found over 300 \"Little Red Dots\", objects that existed between 13.2 an 12.2 billion years ago, and whose nature is currently uncertain",
        "text": null,
        "subreddit": "todayilearned",
        "author": "brazzy42",
        "authorFullname": "t2_mh77j",
        "upvotes": 13637,
        "score": 13637,
        "downs": 0,
        "upvoteRatio": 0.98,
        "scoreHidden": false,
        "comments": 204,
        "subscriberCount": 41571692,
        "totalAwardsReceived": 0,
        "isVideo": false,
        "publishedAt": "2026-02-28T15:03:10.000Z",
        "flair": null,
        "nsfw": false,
        "thumbnail": "https://external-preview.redd.it/jv4EtU_QZlM0w1ZSlNWfvuzvkL-FJ00HGsTsl07LPss.jpeg?width=140&height=139&auto=webp&s=94311e1eec8a572c48b01d8b5cbae2f371396318"
      },
      {
        "platform": "reddit",
        "id": "1ucll2e",
        "name": "t3_1ucll2e",
        "url": "https://www.reddit.com/r/worldnews/comments/1ucll2e/james_webb_telescope_detects_galaxykilling_wind/",
        "title": "James Webb telescope detects 'galaxy-killing wind' near the dawn of time",
        "text": null,
        "subreddit": "worldnews",
        "author": "shdw_fght",
        "authorFullname": "t2_4zuqklab",
        "upvotes": 1472,
        "score": 1472,
        "downs": 0,
        "upvoteRatio": 0.97,
        "scoreHidden": false,
        "comments": 160,
        "subscriberCount": 47507091,
        "totalAwardsReceived": 0,
        "isVideo": false,
        "publishedAt": "2026-06-22T14:08:15.000Z",
        "flair": null,
        "nsfw": false,
        "thumbnail": "https://external-preview.redd.it/MvcbMbmZOw99iMdDsy1JbsvZKf_5VGs-WQ1y5lrYGwo.jpeg?width=140&height=78&auto=webp&s=ff7d6360b316c1006ac4c27398dfc41df784e772"
      }
    ]
  }
}

Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.

Response structure

A successful call returns success, cached, creditsUsed, and a data object with the following fields:

Parameters

Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.

How it works

1. 1. Sign up — get 100 free credits, no card required.
2. 2. Create a key from your dashboard.
3. 3. Send one request to /v1/reddit/search and parse the JSON response.

Use cases

Frequently asked questions

More Reddit APIs