# 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.

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.

1. Make the first call without `cursor`.
2. If `nextCursor` is a string, send the **same input** again with `"cursor": "<nextCursor>"`.
3. Stop when `nextCursor` is `null`, or when `output.found` is `false` (an empty page).

```ts tab="TypeScript"
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 };
}
```

```python tab="Python"
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, spent
```

Things 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; `limit` sets 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 `cursor` input 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.

```bash
# 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
done
```

Keep filters identical while you page: a cursor belongs to the query that produced it.
