---
title: "Search Reddit posts, comments, subreddits, or users"
method: GET
path: "/v1/reddit/search"
---

# Search Reddit posts, comments, subreddits, or users

`GET /v1/reddit/search`

## Request

- Base URL: `https://api.veezee.io`
- URL: `https://api.veezee.io/v1/reddit/search`
- Auth: HTTP bearer

Search all of Reddit by keywords. type picks the target: posts (default), comments (what people actually say about a product, problem, or brand -- unique to Reddit search), subreddits (find communities), users. Pass query as free text up to 256 characters; decompose broad topics into several narrower queries, since result depth per query is capped upstream around a few hundred results. sort applies to posts (relevance|top|new|hot|comment_count) and comments (relevance|top|new); range (past_hour..all_time) applies to posts only; both are rejected with INVALID_INPUT elsewhere. Costs 6 credits per page; a cursor page is a NEW call priced the same way. Returns one page of summaries (author, title or comment text, upvotes, comment_count, created_at, permalink, id) with a cursor; there is no server-side time window on comment search, so for monitoring filter on created_at yourself and poll with sort=new. Fetch full post bodies and discussion threads with reddit_get_post; read one community's feed with reddit_get_subreddit_posts. For high-volume recency sweeps across X instead, use x_search.

## Query parameters

- `query` string, required: Free-text keywords, e.g. 'self hosted photo backup'. Not a URL; use reddit_resolve_url for URLs.
- `type` 'posts' | 'comments' | 'subreddits' | 'users': What to search. 'comments' finds mentions inside discussions; 'subreddits' finds communities.
- `sort` 'relevance' | 'top' | 'new' | 'hot' | 'comment_count': posts: any value; comments: relevance|top|new; invalid for subreddits and users.
- `range` 'past_hour' | 'today' | 'past_week' | 'past_month' | 'past_year' | 'all_time': Time window. posts only.
- `cursor` string: Cursor from a previous page.
- `freshness` 'recent' | 'realtime': recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.
- `max_credits` integer: Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.

## Headers

- `Idempotency-Key` string

## Response `200`

reddit_search envelope (schema_version 2)

- RedditSearchEnvelope
  - `entity` 'reddit_search', required
  - `platform` 'linkedin' | 'reddit' | 'x', nullable, required
  - `canonical_url` string, nullable, required
  - `data_as_of` string, nullable, required
  - `schema_version` '2', required
  - `common` object, required
    - `type` 'posts' | 'comments' | 'subreddits' | 'users', required: Which result array is populated.
    - `posts` object[], nullable, required
      - `id` string, required: Post id with the t3_ prefix. Pass to reddit_get_post.
      - `title` string, nullable, required
      - `author` string, nullable, required: Username without the u/ prefix.
      - `subreddit` object, nullable, required
        - `name` string, required: Subreddit name without the r/ prefix, e.g. 'selfhosted'.
        - `subscribers` integer, nullable, required
      - `created_at` string, nullable, required: ISO 8601.
      - `upvotes` integer, nullable, required
      - `upvote_ratio` number, nullable, required
      - `comment_count` integer, nullable, required
      - `permalink` string, nullable, required: Canonical reddit.com URL.
      - `external_url` string, nullable, required: The linked page for link posts; null for self posts.
      - `preview_text` string, nullable, required: Start of the post body; the full body comes from reddit_get_post.
      - `flair` string, nullable, required
      - `media_type` string, nullable, required
      - `is_promoted` boolean, required: True for promoted ads, which subreddit feeds include only when include_promoted=true. Organic posts are false.
    - `comments` object[], nullable, required
      - `id` string, required: Comment id with the t1_ prefix.
      - `author` string, nullable, required
      - `content` string, nullable, required: Comment text (markdown as written).
      - `created_at` string, nullable, required
      - `upvotes` integer, nullable, required
      - `permalink` string, nullable, required
      - `parent_id` string, nullable, required: t1_ id of the parent comment, or t3_ id when top-level.
      - `depth` integer, nullable, required: 0 = top-level. Only set inside a discussion tree.
      - `post` object, nullable, required: The post this comment belongs to. Only set outside a discussion tree (search, user history).
        - `id` string, nullable, required
        - `title` string, nullable, required
        - `subreddit` object, nullable, required
          - `name` string, required: Subreddit name without the r/ prefix, e.g. 'selfhosted'.
          - `subscribers` integer, nullable, required
    - `subreddits` object[], nullable, required
      - `name` string, required
      - `description` string, nullable, required
      - `subscribers` integer, nullable, required
    - `users` object[], nullable, required
      - `username` string, required
      - `created_at` string, nullable, required
      - `karma` integer, nullable, required
      - `profile_url` string, nullable, required
    - `cursor` string, nullable, required: Pass back to fetch the next page. Null when exhausted.
    - `next_url` string, nullable, required
    - `returned_count` integer, required
    - `truncation_hint` string, nullable, required: Present when results were cut off; says how to narrow or continue.
  - `platform_fields` object, required
  - `freshness` object, nullable, required
    - `source_retrieved_at` string, nullable, required: When the data was fetched from the source. ISO 8601.
    - `served_at` string, required
    - `cache_age_seconds` integer, nullable, required
    - `served_from_cache` boolean, required: True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are.
    - `freshness_requested` 'recent' | 'realtime', required
    - `freshness_served` 'recent' | 'realtime' | 'stale', required
  - `usage` object, required
    - `receipt_id` string, nullable, required
    - `credits_quoted` integer, required
    - `credits_charged` integer, required
    - `balance_remaining` integer, nullable, required
    - `free_tier_hint` string: Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key. Near the daily cap on unclaimed keys it also carries a claim link to relay to your human (claiming adds one-time credits).

## Other responses

- `400`: INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED
- `401`: UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED
- `402`: INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS
- `403`: NOT_ENTITLED | TRIAL_CAP_EXCEEDED
- `404`: NOT_FOUND
- `409`: IDEMPOTENCY_KEY_REUSED
- `413`: PAYLOAD_TOO_LARGE
- `429`: CONCURRENCY_LIMIT | RATE_LIMITED
- `500`: INTERNAL
- `502`: UPSTREAM_UNAVAILABLE
- `503`: BUDGET_EXHAUSTED

---

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