Pagination

List endpoints return results in pages rather than all at once. Cursor-based pagination is the standard across the Spirii API; some existing endpoints use offset-based pagination instead. An endpoint’s reference page lists the exact parameters it accepts, so that is always the source of truth for how a given endpoint pages.

Cursor pagination

The standard. You request a page, and the response hands you a cursor pointing at the next one. You keep following cursors until there are none left. Request parameters

Parameter	Description	Default
`limit`	Number of records to return, from 1 to 100	`25`
`nextPageCursor`	Cursor returned by a previous response, to fetch the next page	—
`previousPageCursor`	Cursor returned by a previous response, to fetch the previous page	—

Response shape

{
  "data": [ /* the records for this page */ ],
  "nextPageCursor": "My0xMDAw",
  "previousPageCursor": null
}

The cursors are opaque strings — don’t parse or build them, only pass back what you received. When there are no further results, nextPageCursor comes back empty.

Page through every result

Request the first page, then keep passing the returned nextPageCursor back until it’s empty:

# First page
curl https://api.spirii.com/v2/chargeboxes?limit=100 \
  -H "Authorization: Bearer <SPIRII_API_KEY>"

# Next page — pass the nextPageCursor from the previous response
curl "https://api.spirii.com/v2/chargeboxes?limit=100&nextPageCursor=My0xMDAw" \
  -H "Authorization: Bearer <SPIRII_API_KEY>"

In code, loop until the cursor runs out:

async function fetchAll() {
  const results = [];
  let cursor;

  do {
    const url = new URL("https://api.spirii.com/v2/chargeboxes");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("nextPageCursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${SPIRII_API_KEY}` },
    });
    const body = await res.json();

    results.push(...body.data);
    cursor = body.nextPageCursor;
  } while (cursor);

  return results;
}

Cursor responses don’t include a total count, so you can’t show “page 3 of 20” or jump to an arbitrary page. You page forward (or back) until the cursor is empty. This keeps paging stable even while records are being added or removed underneath you.

Offset pagination

Some existing endpoints page by offset instead: you ask for a limit and skip a number of records with offset.

Parameter	Description	Default
`limit`	Number of records to return	Varies by endpoint
`offset`	Number of records to skip from the start of the result set	`0`

Offset responses include a count — the total number of records matching your query — so you can calculate how many pages there are. To walk the full set, increase offset by limit on each request until offset reaches count:

# First page
curl "https://api.spirii.com/v2/tokens?limit=500&offset=0" \
  -H "Authorization: Bearer <SPIRII_API_KEY>"

# Second page
curl "https://api.spirii.com/v2/tokens?limit=500&offset=500" \
  -H "Authorization: Bearer <SPIRII_API_KEY>"

Which pagination an endpoint uses

Check the endpoint’s parameters in the API reference: a nextPageCursor parameter means cursor-based, an offset parameter means offset-based. Two differences catch people out when moving between endpoints:

Default and maximum page size vary. A cursor endpoint might default to 25 records (max 100), while an offset endpoint defaults to 500 (max 1000). Set limit explicitly rather than relying on the default.
Only offset responses return a total. If you need a count, read it from count on an offset endpoint; cursor endpoints don’t provide one.

If your integration reads from several endpoints, handle both styles: branch on whether the response returns a nextPageCursor or a count, rather than assuming one scheme everywhere.

Filtering

Narrow and sort list results with query parameters.

API reference

The exact pagination parameters each endpoint accepts.

Get started

Mechanics

Playbooks

Page through every result

Filtering

API reference

​Cursor pagination

​Page through every result

​Offset pagination

​Which pagination an endpoint uses

​Related

Filtering

API reference

Cursor pagination

Page through every result

Offset pagination

Which pagination an endpoint uses

Related