---
title: "List a community's posts: hot, new, rising, top, or controversial"
method: GET
path: "/v1/reddit/subreddits/{name}/posts"
tags: ["Reddit"]
---

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

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

## Request

- Base URL: `https://api.weirapp.io`
- URL: `https://api.weirapp.io/v1/reddit/subreddits/{name}/posts`
- Auth: HTTP bearer

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.

## Path parameters

- `name` string, required: 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.

## Query parameters

- `sort` 'hot' | 'new' | 'rising' | 'top' | 'controversial': Reddit's own orderings. `new` is arrival order, which is what watching a community needs; `hot` is Reddit's default front page.
- `time` 'hour' | 'day' | 'week' | 'month' | 'year' | 'all': Window for `top` and `controversial` only. Defaults to `day` for those sorts.
- `geo` string: Region for `popular` sorted by `hot` only: a country code (`DE`), a US state (`US_CA`), or `GLOBAL`.
- `includeNsfw` 'true' | 'false': 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.
- `limit` integer: Posts per page, before the NSFW rule is applied.
- `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`

Posts in the listing's order, 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)