Pagination

Catalogian uses cursor-based pagination for all list endpoints. Cursors are opaque strings that point to a position in the result set — more reliable than offset-based pagination for data that changes frequently.

How it works

Every paginated response includes a hasMore boolean and a nextCursor string. Pass nextCursor as the cursor query parameter in your next request to get the next page.

# First page
GET /v1/sources/:id/delta?limit=10

# Response includes:
# "hasMore": true,
# "nextCursor": "eyJpZCI6ImV2dF8wMWou..."

# Next page
GET /v1/sources/:id/delta?limit=10&cursor=eyJpZCI6ImV2dF8wMWou...

Paginated endpoints

Response shape

{
  "sourceId": "src_01j...",
  "count": 10,
  "hasMore": true,
  "nextCursor": "eyJpZCI6ImV2dF8wMWou...",
  "events": [ ... ]
}

The array key varies by endpoint (events, rows, or snapshots), but the pagination fields are always the same.

Complete pagination example

Fetch all delta events for a source, page by page:

const API = "https://api.catalogian.com/v1";
const headers = { Authorization: "Bearer cat_live_..." };

async function fetchAllDeltaEvents(sourceId) {
  const allEvents = [];
  let cursor = null;

  do {
    const url = new URL(`${API}/sources/${sourceId}/delta`);
    url.searchParams.set("limit", "200");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, { headers });
    const data = await res.json();

    allEvents.push(...data.events);
    cursor = data.hasMore ? data.nextCursor : null;
  } while (cursor);

  return allEvents;
}

Tips

• •Use the maximum limit if you're paginating through all results — fewer requests means faster completion.
• •Cursors are opaque. Don't parse, modify, or store them long-term. They may change format between API versions.
• •Combine with since on the delta endpoint to paginate only recent events.
• •Cursors are stable — you can resume pagination from a saved cursor as long as the underlying data hasn't been deleted (e.g. by retention policies).