Responses
The envelope every success answers with, and pagination.
The envelope
Every successful call answers with the same shape:
{
"data": [],
"page": { "next_cursor": "…", "has_more": true },
"meta": {
"platform": "reddit",
"endpoint": "subreddit_posts",
"params": { "subreddit": "Python", "sort": "hot" },
"request_id": "req_1f8c2d3e4a5b6c7d",
"api_version": "v1",
"fetched_at": "2026-10-18T09:30:00Z",
"cached": false
}
}datais one object, or a list for endpoints that return many.pageleads to the next page on endpoints that page; it'snullon the others.meta.cachedistruewhen the answer came from the cache;fetched_atsays how old it is.
Pagination
When page.has_more is true, send page.next_cursor as the cursor parameter, with the same other parameters, to
get the next page. On the last page has_more is false and next_cursor is null.
import os
import requests
params = {"subreddit": "Python", "sort": "new"}
while True:
response = requests.get(
f"{os.environ['API_URL']}/v1/reddit/subreddits/posts",
params=params,
headers={"x-api-key": os.environ["API_KEY"]},
timeout=120,
)
body = response.json()
for post in body["data"]:
print(post["title"])
if not body["page"]["has_more"]:
break
params["cursor"] = body["page"]["next_cursor"]Each page is one call and costs one credit. A next page that comes back empty answers 503 EMPTY_PAGE: try again,
or start again from the first page.
Errors
An error answers with its HTTP status and an error body instead of the envelope. See Errors for
every code and when to try again.