Pagination

List endpoints page with cursors, not offsets. The response carries a next_cursor field when more results exist; you echo it back as a query parameter to fetch the next page. Pages are stable — records inserted or deleted between requests do not cause items to appear twice or be skipped. By the end of this page you will know how to walk a list end to end and how to detect the final page.

Request parameters

Default and maximum limit values are not published. Check next_cursor to determine whether more pages exist rather than comparing against an assumed total count.

Response shape

Every list endpoint returns results under a data array. When more pages remain, next_cursor is present. When you have fetched all results, next_cursor is absent or null.

Walk through pages

Fetch the first page without a cursor, then follow next_cursor until it is absent:

# First page
curl "https://api.gavai.app/v1/workspaces/acme/pages?limit=50" \
  -H "Authorization: Bearer gak_live_xxxxxxxxxxxxx"

# Next page — use the next_cursor value from the previous response
curl "https://api.gavai.app/v1/workspaces/acme/pages?limit=50&cursor=cur_01HX..." \
  -H "Authorization: Bearer gak_live_xxxxxxxxxxxxx"

TypeScript, with a do/while loop:

import { GavaiClient } from "@gavai/sdk-typescript";

const client = new GavaiClient(process.env.GAVAI_API_KEY!);

const pages = [];
let cursor: string | undefined;

do {
  const res = await client.workspaces.pages.list("acme", { limit: 50, cursor });
  pages.push(...res.data);
  cursor = res.next_cursor ?? undefined;
} while (cursor);

console.log(`Fetched ${pages.length} pages`);

Termination and edge cases

Signal	What it means
`data` empty, no `next_cursor`	The list is empty or you have consumed everything.
Absent or `null` `next_cursor`	Definitive end of results. A short page is not a reliable end signal — only the absent cursor is.
`404` or `invalid_cursor` on a cursor	The cursor has expired after an extended idle period. Restart pagination from the beginning.

Rate limits

Per-token limits, X-RateLimit-* headers, and the Retry-After contract.

Overview

Resources

Request parameters

Response shape

Walk through pages

Termination and edge cases

Next

Rate limits

​Request parameters

​Response shape

​Walk through pages

​Termination and edge cases

​Next

Rate limits

Request parameters

Response shape

Walk through pages

Termination and edge cases

Next