# Listings and pages



Every endpoint that returns a list of posts, comments, subreddits or users answers with the same envelope:

```jsonc
{
  "subreddit": "golang",      // the subreddit asked for, or null
  "query": null,              // the search query, or null
  "sort": "top",              // the sort Reddit applied
  "count": 3,                 // items in this page
  "items": [ /* posts, comments, subreddits or users */ ],
  "after": "t3_1x0vbyx",      // pass back as after= for the next page; null on the last
  "filtered_nsfw": 0          // NSFW items left out of this page
}
```

The item type depends on the endpoint: [Subreddit](/reddit/subreddit), [Search](/reddit/search), [Duplicates](/reddit/duplicates) and [User posts](/reddit/user-posts) return posts; [Subreddit comments](/reddit/subreddit-comments), [User comments](/reddit/user-comments) and [Comment search](/reddit/search-comments) return comments; [Subreddits](/reddit/subreddits) and `search?type=subreddit` return subreddits; `search?type=user` returns users.

Pages [#pages]

Pass the previous page's `after` to get the next one. Each page is one call and 1 credit.

```bash
curl "https://api.threadapi.dev/v1/reddit/subreddit?sub=golang&sort=new&limit=100&after=t3_1x0vbyx" \
  -H "Authorization: Bearer $THREADAPI_API_KEY"
```

`after` is a Reddit fullname (`t3_…` for posts, `t1_…` for comments, `t5_…` for subreddits, `t2_…` for users) except on comment search, where it is an opaque string. Treat it as opaque everywhere and pass it back unchanged.

Reddit stops a listing at about 1,000 items, whatever the sort. To go further back, narrow the request: a shorter `t` window, a search with `sub`, or a different sort.

NSFW [#nsfw]

Items Reddit marks NSFW are left out unless you pass `nsfw=true`. `filtered_nsfw` counts how many were left out of the page, so a page can hold fewer than `limit` items while `after` is still set.

Reading a subreddit that is itself marked NSFW without `nsfw=true` returns 403 `nsfw_subreddit`:

```json
{"error":{"code":"nsfw_subreddit","message":"This subreddit is marked NSFW. Pass nsfw=true to read it.","retryable":false}}
```

Caching [#caching]

Listings are cached briefly: 30 seconds for `new` and `rising`, a minute for `hot` and search, and 5 minutes for `top` and `controversial` over a day or longer. The `X-Cache-Tier` header says whether the page came from the cache (`L1_LISTING`) or from Reddit (`MISS`). A cached page costs the same 1 credit.