Core concepts
Page through large result sets with cursors, without skipping or repeating items.
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
| Parameter | What it does |
|---|---|
limit | Page size, between 1 and 100. Defaults to 20. |
cursor | The 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.