Pagination
Walk through long results with opaque cursors, both in list and search APIs (cursor and nextCursor) and in account endpoints such as GET /v1/requests.
Last updated
On this page
Everything that can return more than one page uses the same pattern: an opaque cursor. You never compute offsets; you pass back the cursor you were given.
In list and search APIs
APIs that return lists (searches, posts, comments, followers, reviews and so on) take an optional cursor input field and return nextCursor. The output shape is always { <collection>: [...], nextCursor }, for example { "posts": [...], "nextCursor": "…" }, and nextCursor is also repeated at the top level of the envelope.
- Make the first call without
cursor. - If
nextCursoris a string, send the same input again with"cursor": "<nextCursor>". - Stop when
nextCursorisnull, or whenoutput.foundisfalse(an empty page).
const API = 'https://api.primaryapi.com';
const headers = { Authorization: `Bearer ${process.env.PRIMARYAPI_API_KEY}`, 'Content-Type': 'application/json' };
export async function searchAll(query: string, maxPages = 5) {
const posts: unknown[] = [];
let cursor: string | undefined;
let spent = 0;
for (let page = 0; page < maxPages; page++) {
const res = await fetch(`${API}/v1/run/reddit.search`, {
method: 'POST',
headers,
body: JSON.stringify({ query, limit: 100, ...(cursor ? { cursor } : {}) }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.error}`);
spent += body.credits;
if (!body.output.found) break; // no (more) results
posts.push(...body.output.data.posts);
cursor = body.nextCursor ?? undefined;
if (!cursor) break;
}
return { posts, spentCredits: spent };
}import os
import requests
API = "https://api.primaryapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['PRIMARYAPI_API_KEY']}"}
def search_all(query: str, max_pages: int = 5) -> tuple[list, int]:
posts, cursor, spent = [], None, 0
for _ in range(max_pages):
payload = {"query": query, "limit": 100, **({"cursor": cursor} if cursor else {})}
res = requests.post(f"{API}/v1/run/reddit.search", headers=HEADERS, json=payload, timeout=30)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['code']}: {body['error']}")
spent += body["credits"]
if not body["output"]["found"]:
break # no (more) results
posts.extend(body["output"]["data"]["posts"])
cursor = body.get("nextCursor")
if not cursor:
break
return posts, spentThings to know:
- Every page is its own call and is billed on its own, in credits. For per-result APIs you pay for the rows each page returns;
limitsets the page size and the most a page can cost. Put a page budget in your loop, as above. - Cursors are opaque. Pass them back exactly as received, with the same other input fields. Do not parse, build or store them for long: treat them as short-lived. If a cursor is rejected (
400 invalid_input), start again from the first page. - Ordering can shift between pages. Results are live upstream data, so items can move between pages during a long walk. De-duplicate by id if that matters, and never mix cursors from different walks.
- Each API's reference page says whether it supports cursors; look for the
cursorinput and the "Pagination" note.
In account endpoints
Account lists use the same idea with query parameters:
| Endpoint | Page size (limit) | Filters |
|---|---|---|
GET /v1/requests | 1–200, default 50 | sku, keyId, status |
GET /v1/billing/ledger | 1–200, default 50 | none |
GET /v1/billing/orders | 1–200, default 50 | none |
GET /v1/apis | 1–500, default 100 | q, category, platform, status |
They answer { "items": [...], "nextCursor": "…" } (GET /v1/apis also returns total). Pass nextCursor as ?cursor= for the next page; null means you reached the end. Items come newest first in the account lists.
# every failed request of one SKU, page by page
cursor=""
while :; do
page=$(curl -sS "https://api.primaryapi.com/v1/requests?status=failed&sku=reddit.search&limit=200${cursor:+&cursor=$cursor}" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY")
echo "$page" | jq -c '.items[] | {requestId, errorCode, createdAt}'
cursor=$(echo "$page" | jq -r '.nextCursor // empty')
[ -z "$cursor" ] && break
doneKeep filters identical while you page: a cursor belongs to the query that produced it.