Listings and pages

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

{
  "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, Search, Duplicates and User posts return posts; Subreddit comments, User comments and Comment search return comments; Subreddits and search?type=subreddit return subreddits; search?type=user returns users.

Pages

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

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

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:

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

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.