Weir

Search posts within one subreddit

POST /v1/reddit/subreddits/{name}/search

Posts matching a query inside the community in the path. The body cannot widen the search beyond it. To find communities rather than posts, use POST /v1/reddit/search/subreddits.

Price: 1 credit per call, plus 3 credits per Reddit post returned. Failed and refused calls cost nothing.

Rate limit: Counts as 2 requests against your per-minute rate limit.

MCP tool: search_subreddit, on every MCP connection.

Requires an API key, sent as Authorization: Bearer <key>.

Request

curl --request POST \
  --url https://api.weirapp.io/v1/reddit/subreddits/NAME/search \
  --header "Authorization: Bearer $WEIR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"query":"payment failures"}'

Path parameters

Field Type Required Notes
name string yes Community name without the r/ prefix: 3-21 letters, digits, or underscores starting with a letter or digit, or a two-letter language community such as de. · matches ^(?:[A-Za-z0-9][A-Za-z0-9_]{2,20}|[A-Za-z]{2})$

Body

Field Type Required Notes
query string yes Reddit search syntax: words, "exact phrases", OR, -exclusions, and field operators such as title:, author:, flair:, site:example.com, url:, self:yes. · 1–500 chars
sort string no new is arrival order; comments ranks by comment count. · relevance, hot, top, new, comments, default "relevance"
time string no Only posts created within this window. · all, year, month, week, day, hour, default "all"
includeNsfw boolean no Include results marked NSFW. Off by default; what it removes is reported in meta.omittedNsfw. · default false
limit integer no 1–100, default 25
cursor string no 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. · 1–4096 chars

Response

Reddit posts restricted to the named subreddit.

200

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

Errors

Status Meaning What to do
400 The request failed validation. The request was malformed. The details object names the field.
401 The API key is missing, malformed, expired, or revoked. The key is missing, malformed, revoked, or expired.
402 The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes. Out of credits. Never retry. Only a person can clear it, by adding credits at https://weirapp.io/dashboard/billing. Retrying never will.
403 The API key does not carry the scope this route requires. The key is valid but lacks the scope this operation needs.
404 The requested resource does not exist. No such resource, or it is not public.
429 The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again. Rate limited. Retryable: wait for Retry-After, then try again.
500 An unexpected error occurred. Something failed on our side. Retryable with backoff.
503 The source is temporarily unavailable. The request is safe to retry. A source was unreachable. Retryable with backoff.

View this page as Markdown