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": 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 (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. Envelope includes cached + cachedAt on hits. |
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. Hits include cached + cachedAt. 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 proxies, rate limits, retries, and authentication for you.
Why can score be 0 when upvoteRatio is 0.36?
score is Reddit's own score field — Captapi does not compute ups−downs (public JSON almost always sends downs: 0). New posts often have hide_score: score/upvotes stay 0 while upvoteRatio is still filled. Check scoreHidden; do not treat a zero score as worthless until the hide window ends.
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 (ScrapeCreators-style comments[]) is a separate surface on the backlog.
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. Hits include cached + cachedAt. 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