---
title: "Search public Reddit posts"
method: POST
path: "/v1/reddit/search"
tags: ["Reddit"]
---

# Search public Reddit posts

`POST /v1/reddit/search`

## Request

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

Posts matching a query across Reddit, or within the communities named in `subreddit` or
`subreddits`. Reddit's search covers post titles and bodies only — it does not search
comment text; to find mentions in comments, read a community's comment stream with
`GET /v1/reddit/subreddits/{name}/comments` or watch it with a `subreddit_comments` monitor.

To list a community without a keyword, use `GET /v1/reddit/subreddits/{name}/posts`. NSFW
posts are excluded unless `includeNsfw` is true.

## Request body

- object
  - `query` string, required: Reddit search syntax: words, `"exact phrases"`, `OR`, `-exclusions`, and field operators such as `title:`, `author:`, `flair:`, `site:example.com`, `url:`, `self:yes`.
  - `subreddit` string: Restrict the search to one community, by name without `r/`.
  - `subreddits` string[]: Restrict the search to several communities at once (up to 25).
  - `sort` 'relevance' | 'hot' | 'top' | 'new' | 'comments': `new` is arrival order; `comments` ranks by comment count.
  - `time` 'all' | 'year' | 'month' | 'week' | 'day' | 'hour': Only posts created within this window.
  - `includeNsfw` boolean: Include results marked NSFW. Off by default; what it removes is reported in `meta.omittedNsfw`.
  - `limit` integer
  - `cursor` string: `meta.nextCursor` from the previous page, unchanged. Opaque, signed, and bound to the other parameters: change any of them and start again without a cursor.

## Response `200`

Reddit posts, in Reddit's own field names.

- object
  - `data` object[], required
    - `id` string, required: Reddit's base-36 post id, without the `t3_` prefix.
    - `subreddit` string, required: Community name without the `r/` prefix.
    - `title` string, required
    - `selftext` string, required: Body text. Empty for a link post.
    - `author` string, required: Username without the `u/` prefix. `[deleted]` if removed.
    - `permalink` string, required: Path on reddit.com, beginning with a slash.
    - `url` string, required: Absolute URL to the post.
    - `score` integer, required: Upvotes minus downvotes. Can be negative, and is fuzzed by Reddit.
    - `upvoteRatio` number, required: Fraction of votes that were upvotes.
    - `numComments` integer, required
    - `over18` boolean, required: Marked NSFW by the author or a moderator.
    - `createdUtc` number, required: Creation time in epoch seconds, as Reddit reports it.
    - `createdAt` string, date-time, required: The same instant as `createdUtc`, in ISO 8601.
    - `domain` string, required: `self.<subreddit>` for a text post; otherwise the host the post links to.
    - `isSelf` boolean, required: A text post rather than a link.
    - `urlOverriddenByDest` string, nullable, required: Where a link post points. Null for a text post.
    - `linkFlairText` string, nullable, required: The post's flair, such as `Question` or `Hiring`. Null when it has none.
    - `authorFlairText` string, nullable, required: The author's flair in this community.
    - `distinguished` string, nullable, required: `moderator` or `admin` when posted in an official capacity; otherwise null.
    - `stickied` boolean, required: Pinned to the top of the community.
    - `locked` boolean, required: New comments are disabled.
    - `archived` boolean, required: Past Reddit's archive age: no new comments or votes.
    - `spoiler` boolean, required
    - `edited` number, nullable, required: When the post was last edited, in epoch seconds. Null if it never was.
    - `numCrossposts` integer, required
    - `crosspostParent` string, nullable, required: The original post's id, without `t3_`, when this post is a crosspost.
    - `removedByCategory` string, nullable, required: Why the post was removed: `moderator`, `deleted`, `author`, `automod_filtered`, `reddit`, and so on. Null while it is visible.
    - `subredditSubscribers` integer, required: Members of the community at the time the post was read.
    - `postHint` string, nullable, required: What the post holds when Reddit says: `image`, `link`, `hosted:video`, `self`.
    - `isVideo` boolean, required
  - `meta` object, required
    - `requestId` string, required
    - `nextCursor` string, nullable
    - `omittedNsfw` integer: Items removed from this page because they are marked NSFW and `includeNsfw` is false. Absent when nothing was removed. A page can be short, or even empty with a non-null `nextCursor`, because of it.

## Other responses

- `400`: The request failed validation.
- `401`: The API key is missing, malformed, expired, or revoked.
- `402`: The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes.
- `403`: The API key does not carry the scope this route requires.
- `404`: The requested resource does not exist.
- `429`: The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again.
- `500`: An unexpected error occurred.
- `503`: The source is temporarily unavailable. The request is safe to retry.

---

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