Weir

List a community's posts: hot, new, rising, top, or controversial

GET /v1/reddit/subreddits/{name}/posts

A community's own listing, with no keyword: everything new in r/saas, or this week's top posts in r/startups. Use this rather than search when the community is the filter — Reddit's search needs a query and cannot express "everything".

name also takes popular, all, or several communities joined with +, which reads them as one listing in a single call (and is billed as one request).

Pages are newest-cursor-forward and stop at about 1,000 posts, Reddit's own ceiling, where nextCursor becomes null. NSFW posts are left out unless includeNsfw=true; how many were left out is in meta.omittedNsfw. A community that does not exist, or is private, banned, or quarantined, is a 404 whose details.reason says which.

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: get_subreddit_posts, on every MCP connection.

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

Request

curl --request GET \
  --url https://api.weirapp.io/v1/reddit/subreddits/NAME/posts \
  --header "Authorization: Bearer $WEIR_API_KEY"

Path parameters

Field Type Required Notes
name string yes A community name without r/; popular or all for the site-wide listings; or up to 25 communities joined with + (saas+startups+entrepreneur) to read them as one listing in a single call. · matches ^(?:[A-Za-z0-9][A-Za-z0-9_]{2,20}|[A-Za-z]{2})(?:\+(?:[A-Za-z0-9][A-Za-z0-9_]{2,20}|[A-Za-z]{2})){0,24}$

Query parameters

Field Type Required Notes
sort string no Reddit's own orderings. new is arrival order, which is what watching a community needs; hot is Reddit's default front page. · hot, new, rising, top, controversial, default "hot"
time string no Window for top and controversial only. Defaults to day for those sorts. · hour, day, week, month, year, all
geo string no Region for popular sorted by hot only: a country code (DE), a US state (US_CA), or GLOBAL. · matches ^(?:GLOBAL|[A-Z]{2}|US_[A-Z]{2})$
includeNsfw string no Include posts marked NSFW. Off by default; what it removes is reported in meta.omittedNsfw, so a short or empty page is never mistaken for a quiet one. · true, false, default "false"
limit integer no Posts per page, before the NSFW rule is applied. · 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

Posts in the listing's order, in Reddit's own field names.

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