Pagination

Cursor-based, always

Every list endpoint paginates with an opaque cursor, never a numeric offset. Cursors are stable under concurrent writes, so you never skip or repeat rows while paging — the trade-off page-number pagination can't make.

Pass an optional limit (page size) and, for every page after the first, the cursor returned by the previous response:

curl "https://api.example.com/api/v1/products?limit=50" \
  -H "X-API-Key: pie_live_..."

Reading the response

List responses wrap the rows in items and expose a nextCursor. When nextCursor is null, you have reached the last page:

{
  "items": [ /* … up to `limit` records … */ ],
  "nextCursor": "eyJpZCI6IjAx..."
}

Paging through every record

Follow the cursor until it comes back null:

let cursor = null;
do {
  const url = new URL("https://api.example.com/api/v1/products");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, { headers: { "X-API-Key": key } });
  const page = await res.json();

  for (const product of page.items) handle(product);
  cursor = page.nextCursor;
} while (cursor);