Pagination

List endpoints use cursor-based pagination. Cursors are opaque — treat them as strings, never parse their contents.

---

List response shape

{
  "object": "list",
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InN1Yl9hYmMiLCJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yMVQxMDozMDowMFoifQ",
  "previous_cursor": null,
  "request_id": "req_abc123"
}

---

Parameters

Parameter	Default	Description
limit	25	Page size (1–100)
starting_after	—	Return items after this cursor (forward pagination)
ending_before	—	Return items before this cursor (backward pagination)

starting_after and ending_before are mutually exclusive.

---

Forward pagination

curl

# First page
curl "https://api.xavigate.com/v1/nature/subjects?limit=25" \
  -H "Authorization: Bearer test_sk_YOUR_KEY"

# Next page — use next_cursor from previous response
curl "https://api.xavigate.com/v1/nature/subjects?limit=25&starting_after=eyJpZCI6..." \
  -H "Authorization: Bearer test_sk_YOUR_KEY"

TypeScript

// Auto-pagination — the SDK handles cursor management
for await (const subject of client.nature.subjects.list({ limit: 25 })) {
  console.log(subject.id);
}

// Manual pagination
let cursor: string | null = null;
do {
  const page = await client.nature.subjects.list({
    limit: 25,
    ...(cursor ? { starting_after: cursor } : {}),
  });
  for (const subject of page.data) {
    console.log(subject.id);
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

Python

# Auto-pagination — the SDK handles cursor management
for subject in client.nature.subjects.list(limit=25):
    print(subject.id)

# Manual pagination
cursor = None
while True:
    page = client.nature.subjects.list(limit=25, starting_after=cursor)
    for subject in page.data:
        print(subject.id)
    if not page.has_more:
        break
    cursor = page.next_cursor

---

Why cursors (not offsets)

Offset pagination (?page=2&per_page=25) breaks when items are inserted or deleted between page requests — you skip records or see duplicates. Cursor pagination pins to a specific record position, giving consistent results regardless of concurrent writes. For a dataset that changes frequently (new subjects being created), cursors are the correct choice.