Pagination

Page through lists with limit and cursor, and the query string rules every endpoint follows.

List endpoints return one page at a time:

{
  "data": [],
  "nextCursor": "WzEsIm1aR..."
}

data holds the page’s items. nextCursor is the cursor for the next page, or null on the last page.

Request the next page

Send nextCursor as the cursor query parameter, with the same filters as the first request. You can change limit between pages.

curl "https://api.zerogen.com/v1/generations?projectId=5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d&cursor=WzEsIm1aR..." \
  -H "Authorization: Bearer $ZEROGEN_API_KEY"

A cursor continues only the list and filters it came from. Sent with other filters, it fails with 400 validation_failed and param set to cursor. Treat cursors as opaque strings.

Endpoint	Default limit	Largest limit
GET /v1/models	20	50
GET /v1/generations	10	20

GET /v1/generations lists newest first.

The following Node.js example reads every page of your generations:

const API = "https://api.zerogen.com/v1";
const auth = { Authorization: `Bearer ${process.env.ZEROGEN_API_KEY}` };

const generations = [];
let cursor = null;
do {
  const query = new URLSearchParams({ limit: "20" });
  if (cursor) query.set("cursor", cursor);
  const response = await fetch(`${API}/generations?${query}`, { headers: auth });
  const page = await response.json();
  if (!response.ok) throw new Error(`${page.error.code}: ${page.error.message}`);
  generations.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);

Query string rules

Every endpoint reads its query string the same way:

• An unknown query parameter fails with 400 invalid_request, and param names it.
• A parameter sent more than once fails with 400 invalid_request.
• A value that isn’t valid fails with 400 validation_failed, and param names the parameter.
• An ID in the path is a UUID. Anything else returns 404 not_found, as an unknown ID does.