API Pagination

Tempo list endpoints share one pagination contract. Use cursor pagination for stable traversal and deep reads. Use page pagination only when an endpoint supports it and you need a shallow, page-numbered UI.

Tempo API pagination modes

Cursor pagination anchors traversal to a row position, so the next cursor continues from exactly where the previous page ended, even when new rows arrive at the head of a feed between requests.

Page pagination is positional. If new rows arrive at the head of a feed, items can shift across page boundaries, which can duplicate or skip results. Some endpoints support cursor pagination only.

Pagination request parameters

Pagination response envelope

List endpoints return a common envelope:

{
  "data": [ /* items for this page */ ],
  "nextCursor": "WzIzNDU2Nzg5LDBd",
  "meta": {
    "totalCount": 42,
    "totalCountCapped": false
  }
}

Cursor pagination for Tempo API lists

Fetch the first page without a cursor:

curl 'https://api.tempo.xyz/v1/tokens?limit=100' \
  --header 'Authorization: Bearer tempo:sk:...'

The response includes nextCursor when another page is available:

{
  "data": [ /* items for this page */ ],
  "nextCursor": "WzIzNDU2Nzg5LDBd",
  "meta": {}
}

Fetch the next page by passing that value back as cursor:

curl --get 'https://api.tempo.xyz/v1/tokens' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'cursor=WzIzNDU2Nzg5LDBd' \
  --header 'Authorization: Bearer tempo:sk:...'

Keep going until nextCursor is null:

{
  "data": [ /* final page items */ ],
  "nextCursor": null,
  "meta": {}
}

Page pagination for shallow Tempo API lists

Use page only for shallow, page-numbered interfaces:

curl 'https://api.tempo.xyz/v1/tokens?limit=25&page=2' \
  --header 'Authorization: Bearer tempo:sk:...'

page is 1-indexed:

• page=1 returns the head page.
• page=2 returns the next positional page.
• page × limit must be at most 10,000.

For anything deeper than 10,000 rows, use cursor pagination. Some endpoints support cursor pagination only — this is common when each returned item is derived from a variable number of underlying rows, which makes positional page boundaries unstable.

Count results in paginated responses

Counts are optional. Request them with include=totalCount:

curl 'https://api.tempo.xyz/v1/tokens?limit=50&include=totalCount' \
  --header 'Authorization: Bearer tempo:sk:...'

The count is computed by a capped subquery up to 10,000 matched rows:

{
  "data": [ /* items for this page */ ],
  "nextCursor": "WzIzNDU2Nzg5LDBd",
  "meta": {
    "totalCount": 10000,
    "totalCountCapped": true
  }
}

• When meta.totalCountCapped is false, meta.totalCount is exact.
• When meta.totalCountCapped is true, meta.totalCount is a lower bound: there are at least that many matches.
• Counts are independent of pagination. Use nextCursor, not totalCount, to decide whether to request another page.

Pagination best practices for Tempo API clients

• Prefer cursor pagination for integrations, sync jobs, exports, and live feeds.
• Use the largest limit your workload can handle, up to 200, to reduce round trips.
• Persist nextCursor if you need to resume traversal later.
• Pass cursors back verbatim, and URL-encode them when placing them in a query string.
• Stop only when nextCursor is null.
• Use page pagination only for shallow UI navigation where duplicate or skipped rows on a live feed are acceptable.