---
title: "Search Posts"
method: GET
path: "/api/reddit/search"
tags: ["Listings & Search"]
---

# Search Posts

`GET /api/reddit/search`

## Request

- Base URL: `https://api.redditapis.com`
- URL: `https://api.redditapis.com/api/reddit/search`
- Auth: HTTP bearer

Full-text post search, optionally scoped to a subreddit. Advanced filters (score, comments, media, flags) are applied to the returned page and add a `meta` block (fetched / returned / filtered_out); paginate with `after` to filter more. Cost: $0.0015 per call.

## Query parameters

- `q` string, required
- `subreddit` string
- `sort` string
- `t` string
- `nsfw` boolean
- `limit` integer
- `after` string
- `min_score` integer
- `max_score` integer
- `min_comments` integer
- `max_comments` integer
- `is_video` boolean
- `is_self` boolean
- `over_18` boolean
- `locked` boolean
- `stickied` boolean
- `spoiler` boolean
- `contest_mode` boolean
- `sort_type` string

## Response `200`

Successful response.

- object
  - `posts` object[]
    - `id` string
    - `name` string
    - `title` string
    - `author` string
    - `author_info` object, nullable
    - `permalink` string
    - `url` string
    - `link_url` string, nullable
    - `text` string, nullable
    - `subreddit` string
    - `upvotes` integer
    - `comments` integer
    - `upvote_ratio` number, nullable
    - `over_18` boolean
    - `stickied` boolean
    - `locked` boolean
    - `spoiler` boolean
    - `is_self` boolean
    - `is_crosspost` boolean
    - `crosspost_origin` object, nullable
    - `link_flair_text` string, nullable
    - `link_flair_template_id` string, nullable
    - `created_utc` number, nullable
    - `created` string, nullable
  - `after` string, nullable: Opaque pagination cursor; null when no next page is offered.
  - `exhausted_reason` string, nullable: Present only when `after` is null: why the listing stopped.
  - `listing_status` string, nullable: complete | truncated | unknown. Only `complete` means you have every item.
  - `items_returned` integer, nullable: Running item count across the pages walked so far.
  - `final_page_items` integer, nullable: Items on the last page served.
  - `hint` string, nullable: Human-readable next step for this exhausted_reason.
  - `meta` object, nullable

## Other responses

- `400`: Bad request — missing or invalid parameters.
- `401`: Missing Bearer token.
- `402`: Your account balance does not cover this call, so nothing was charged and the request was not served. The response body is {"error":"Insufficient credits","top_up_url":"https://www.redditapis.com/dashboard/buy-credits","message":"..."}; error keeps that exact wording. This is a billing state, not a bad request: the same call succeeds once the balance is topped up, and retrying without topping up returns 402 again, which is why it carries Retry-After: 3600. Top up at the top_up_url, then call again at once; the header does not apply after a top-up. Read the remaining balance any time from GET /account/me, which is free and never returns this error. Distinct from the 402 on the monitoring endpoints, which is about plan entitlements rather than credits.
- `403`: Invalid Bearer token.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error.

---

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