---
title: "Reddit Search API"
method: GET
path: "/v1/reddit/search"
tags: ["Reddit"]
---

# Reddit Search API

`GET /v1/reddit/search`

## Request

- Base URL: `https://api.captapi.com`
- URL: `https://api.captapi.com/v1/reddit/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Reddit site-wide post search — sort + timeframe + cursor, score/upvoteRatio, authorFullname.

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 (always "t3_" + id), title, url, subreddit, author + authorFullname (t2_…), score, comments, ISO publishedAt, nsfw, crosspostOf and duplicateOfId (first same-author+title row on this page, else null). Reddit's search page shows a result card, not the post body, so text, upvoteRatio, scoreHidden, flair, isVideo, thumbnail and subscriberCount are null — call Post Details for the full post. Reddit's search returns 7–25 posts per page; one call chains up to three pages to reach limit, and nextCursor (an opaque string) resumes exactly where the response stopped. Cursors issued before 14 Oct 2026 are rejected with 400 INVALID_CURSOR. This endpoint returns posts only — not a comments[] or media[] search surface. A miss is 503 UPSTREAM_UNAVAILABLE at 0 credits. Flat 2 credits. Pass cache=true for the 24h shared cache.

Docs: https://captapi.com/apis/reddit-search

## Query parameters

- `q` string, required
- `limit` integer
- `sort` string
- `timeframe` string
- `cursor` string
- `cache` boolean

## Response `200`

Success. The data object for this endpoint.

- object
  - `success` unknown, required
  - `data` object, required
    - `query` string: The search query you sent.
    - `sort` string: Sort. Example: "relevance".
    - `timeframe` unknown
    - `totalReturned` integer: Number of items returned in this response.
    - `nextCursor` string: Cursor to pass for the next page of results. May be null when the platform does not expose deep pagination (e.g. some Facebook Ad Library searches).
    - `hasMore` boolean: Whether more results are available beyond this page. When true, pass nextCursor to fetch the next page.
    - `results` object[]
      - `platform` string: Platform identifier for this response (matches the endpoint's platform).
      - `id` string: Id of this results item.
      - `name` string: Name of this results item.
      - `url` string: Canonical URL of the item.
      - `title` string: Title of this results item.
      - `text` unknown
      - `subreddit` string: Subreddit the post belongs to.
      - `author` string: Author name or handle.
      - `authorFullname` string: Stable Reddit account fullname (t2_…). Prefer this over author for joins.
      - `upvotes` integer: Upvote count.
      - `score` integer: Reddit's authoritative post score field (not ups−downs). Public JSON almost always zeros downs. hide_score does not zero this field — there is no upvotes twin.
      - `upvoteRatio` number: Upvote ratio 0–1 when Reddit exposes it — an independent controversy signal, not a stand-in for a hidden score.
      - `scoreHidden` boolean: true when Reddit hide_score is set (typically new posts). This is a UI flag — it does not mean score is 0.
      - `comments` integer: Comment count.
      - `subscriberCount` integer: Subscriber count (channel, subreddit, or similar).
      - `isVideo` boolean: Whether the item is a video.
      - `publishedAt` string: Publish date (ISO 8601) when the platform exposes an absolute timestamp.
      - `flair` unknown
      - `nsfw` boolean: Whether the content is marked NSFW.
      - `thumbnail` string: Thumbnail image URL.

## Other responses

- `400`: Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.
- `401`: Missing, invalid or revoked API key. Not billed.
- `402`: Not enough credits for this request. Not billed.
- `404`: The resource does not exist or is not public. Not billed.
- `422`: A required parameter is missing or has the wrong type. Not billed.
- `429`: Rate limit reached. Wait for Retry-After seconds. Not billed.
- `502`: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.

---

[API](https://skmtc.dev/captapi/apis/captapi-api.md) · [All operations](https://skmtc.dev/captapi/apis/captapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/captapi/apis/captapi-api/revisions/c9b9ac5ff1bd?raw)