How to run a Reddit search
GET request to /v1/reddit/search with your input. You get clean JSON back in seconds for 2 credits per call — no OAuth, scraping or platform SDKs. Reddit site-wide post search — sort + timeframe + cursor, score/upvoteRatio, authorFullname. Flat 2 credits.How to run a Reddit search (step by step)
- 1
Get a free API key
Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.
- 2
Call the Reddit Search API
Send an authenticated GET request to /v1/reddit/search with your input. No OAuth, no scraping setup.
- 3
Read the JSON response
Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.
Code example
curl "https://api.captapi.com/v1/reddit/search?q=james%20webb" \
-H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."What the response looks like
{
"success": true,
"data": {
"query": "james webb",
"sort": "relevance",
"timeframe": null,
"totalReturned": 2,
"nextCursor": "h2:0:1x7d9f0.1x6sa1b:eyJjYW5kaWRhdGVzX3JldHVybmVkIjoie1wic2VjdGlvbl8xX3BpcGVsaW5lXzBfZ2xvYmFsX21vZGlmaWVyc1wiOlwiMVwiLFwic2VjdGlvbl8xX3BpcGVsaW5lXzFfbG9jYWxfbW9kaWZpZXJzXCI6XCIyXCIsXCJzZWN0aW9uXzJfcGlwZWxpbmVfOF9keW5hbWljXzBfcG9zdF9zZWFyY2hcIjpcIjdcIixcInNlY3Rpb25fM19waXBlbGluZV8wX2R5bmFtaWNfMF9zdWJyZWRkaXRfc2VhcmNoXCI6XCI1XCIsXCJzZWN0aW9uXzNfcGlwZWxpbmVfMF9keW5hbWljXzFfYXV0aG9yX3NlYXJjaFwiOlwiMVwifSIsImV4cGVyaWVuY2Vfc2VsZWN0aW9uIjoicG9zdHNfdjIiLCJleHBlcmllbmNlX3ZlcnNpb24iOiJkZXNrdG9wIiwic2VjdGlvbl8yX3BpcGVsaW5lXzhfZHluYW1pY18wX3Bvc3Rfc2VhcmNoIjoiNyJ9",
"hasMore": true,
"results": [
{
"platform": "reddit",
"id": "1x7d9f0",
"name": "t3_1x7d9f0",
"url": "https://www.reddit.com/r/AccessibleAnarchy/comments/1x7d9f0/nasa_actively_recruited_nazis_in_2021_nasa_named/",
"title": "NASA actively recruited Nazis. In 2021 NASA named the james webb space telescope after someone complicit in the purging of queer people from NASA. It has been the most advanced and powerful telescope ever built. Do not mistake a clean reputation for an organization being on our side.",
"text": null,
"subreddit": "AccessibleAnarchy",
"author": "RosethornRanger",
"authorFullname": "t2_10yyhc4uob",
"score": 318,
"upvoteRatio": null,
"scoreHidden": null,
"comments": 19,
"subscriberCount": null,
"isVideo": null,
"publishedAt": "2026-10-16T11:04:34.000Z",
"flair": null,
"nsfw": false,
"thumbnail": null,
"crosspostOf": null,
"duplicateOfId": null
},
{
"platform": "reddit",
"id": "1x6sa1b",
"name": "t3_1x6sa1b",
"url": "https://www.reddit.com/r/aliens/comments/1x6sa1b/mysterious_signal_from_empty_space_the_james_webb/",
"title": "Mysterious signal from empty space: The James Webb Space Telescope has detected an unexplained signal in deep space that has stumped astronomers",
"text": null,
"subreddit": "aliens",
"author": "ua-stena",
"authorFullname": "t2_32cwok23",
"score": 942,
"upvoteRatio": null,
"scoreHidden": null,
"comments": 95,
"subscriberCount": null,
"isVideo": null,
"publishedAt": "2026-10-15T17:41:30.000Z",
"flair": null,
"nsfw": false,
"thumbnail": null,
"crosspostOf": null,
"duplicateOfId": null
}
]
}
}Billing metadata (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | Keyword or phrase to search Reddit posts site-wide (min 2 characters). |
| sort | string | No | relevance (default) | new | top | hot | comments (alias: comment_count). |
| timeframe | string | No | For sort=top or comments: hour | day | week | month | year | all (default all). |
| limit | integer | No | Max items to return (default 25, max 200). Flat 2 credits per call. |
| cursor | string | No | Pagination cursor. Leave empty for the first page; then pass the nextCursor value returned in the previous response. |
| cache | boolean | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. |
Frequently asked questions
What does the Reddit Search API do?
The Reddit Search API lets you search and return matching results from a public Reddit query using one GET request to /v1/reddit/search. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the Reddit Search API cost?
Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.
Do I need a Reddit API key or OAuth?
No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle access, rate limits, retries, and authentication for you.
Why are text and upvoteRatio null in search results?
Reddit's search page shows a result card — title, author, subreddit, score, comment count and date — not the post body or vote ratio. Call Post Details with the result's url when you need the full post.
Why did the same post appear three times?
Reddit search returns separately posted copies (same author + title, different ids and subreddits). We do not drop them — you paid for Reddit's page. crosspostOf is Reddit's parent id when this row is a crosspost. duplicateOfId points at the first same-author+title row on this page (null on the first). Filter on those if you want unique titles.
Can I search comments, not just posts?
Not on this endpoint — results are posts only (kind=t3). For discussion text under a known post, use Post Comments. Site-wide comment search is a separate surface on the backlog.
Why can a 503 take longer than a success?
It shouldn't now. Zero hits are 200 results:[]. A true upstream miss is 503 UPSTREAM_UNAVAILABLE (retryable, Retry-After header) within 12 seconds at 0 credits. A typical success is ~4–5s.
Is the Reddit Search API suitable for production use?
Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.
Ready to run a Reddit search?
Start free with 100 credits — no credit card required.
Get your free API key