# 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](/mcp) connection.

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

## Request

```bash
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. |