How to Handle Pagination

List endpoints in the Ligantic API are paginated. You control limit, offset, and cursor directly.

This guide shows you how to page through list results with offset paging (for "give me page N") and with a loop until the result set is exhausted (for "give me everything").

The Pagination Parameters

Most list methods accept a params object with these fields:

• limit — the page size.
• offset — the number of Records to skip.
• cursor — a position marker (not all endpoints use it; limit/offset are the common pair).

For example, records.list(spaceId, schemaId, { limit, offset }).

Offset Paging

Request a specific page by setting offset:

const page = await client.records.list(spaceId, schemaId, {
  limit: 50,
  offset: 100, // skip the first 100 Records
});

if (page.ok) {
  const records = page.value.entities; // the Records on this page
  const total = page.value.count; // total Records in the Schema
}

The list result carries entities (the page), plus count, offset, and limit so you can compute how many pages remain.

Loop Until Exhausted

To fetch every Record, keep requesting pages until a page comes back with fewer Records than limit:

const pageSize = 100;
let offset = 0;
const all = [];

for (;;) {
  const page = await client.records.list(spaceId, schemaId, {
    limit: pageSize,
    offset,
  });
  if (!page.ok) {
    throw new Error(`list failed: ${page.error.code} ${page.error.message}`);
  }
  const batch = page.value.entities;
  all.push(...batch);
  if (batch.length < pageSize) break; // last page
  offset += pageSize;
}

The CLI

The CLI exposes --limit and --offset on the list commands that paginate, as listed under CLI Command Reference — Records:

ligantic records list customer --limit 50 --offset 0

When the page does not cover the full result set, the table ends with a pagination footer, for example 50 of 307 (use --limit/--offset for more).

Add --json to emit machine-readable JSON. For records list, --json prints the full API result — the page plus the count/offset/limit metadata:

ligantic records list customer --limit 50 --offset 0 --json
# → { "records": [ … ], "count": 307, "offset": 0, "limit": 50 }

You still drive paging with --limit and --offset; the metadata tells you how many pages remain.

Limitations

• Offset paging is fine for moderate result sets. For very large or frequently mutating sets, prefer filtering and sorting to narrow the set before paging.