Skip to main content

Pagination

List endpoints return a page of results plus an opaque cursor for the next page:

{
  "data": [ /* … up to `limit` items … */ ],
  "cursor": "eyJQSyI6ICJ0MSIsIC..."
}

Fetching the next page​

Pass the cursor back as a query parameter. When there are no more results, the response cursor is null.

# First page
curl "https://{host}/v1/employees?limit=50" -H "Authorization: Bearer sk_…"

# Next page — pass the cursor from the previous response
curl "https://{host}/v1/employees?limit=50&cursor=eyJQSyI6…" \
  -H "Authorization: Bearer sk_…"

Rules​

  • Treat the cursor as opaque. It encodes internal paging state; do not parse, modify, or construct it. Only ever send back a cursor you received — an invalid or corrupted cursor is rejected with 400 (it is never silently ignored), so a truncated cursor surfaces as an error rather than restarting your loop.
  • limit defaults to 20 and is capped at 100.
  • Filtering parameters (e.g. sectorId, costCenterId on /employees) ride the underlying index, so they are safe to combine with pagination — you will never miss a matching record across pages.

Looping safely​

cursor = None
while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    page = get("/v1/employees", params=params)
    process(page["data"])
    cursor = page["cursor"]
    if not cursor:
        break