Cursor pagination

List endpoints return results in pages. Every list response includes a has_more flag and a cursor for the next page:

{
  "data": [
    { "id": "ord_1042", "status": "shipped" },
    { "id": "ord_1041", "status": "processing" }
  ],
  "has_more": true,
  "next_cursor": "ord_1041"
}

To get the next page, pass the cursor as a query parameter:

curl "https://api.example.com/v1/orders?limit=2&cursor=ord_1041" \
  -H "Authorization: Bearer $API_KEY"

When has_more is false, you've reached the end.

Why cursors

Cursor pagination is stable under writes. Offset-based pagination skips or repeats items when resources are created or deleted mid-scroll. With cursors, each page picks up exactly where the last one left off, no matter what changed in between.

Parameters

ParameterWhat it does
limitPage size, between 1 and 100. Defaults to 20.
cursorThe next_cursor from the previous page. Omit for the first page.

Walk every page

async function listAllOrders() {
  const orders = []
  let cursor = null

  do {
    const url = new URL('https://api.example.com/v1/orders')
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.API_KEY}` },
    })
    if (!response.ok) throw new Error(`Request failed: ${response.status}`)
    const body = await response.json()

    orders.push(...body.data)
    cursor = body.next_cursor
  } while (cursor)

  return orders
}
Watch your rate limit

Walking a large result set means many requests. Use the largest limit you need, and check your remaining quota with the rate limit headers. See Rate limits.

Next steps