---
title: "Pagination"
description: "Page through large result sets with cursors, without skipping or repeating items."
url: "https://nov18-prod-sg.movespot.fyi/guides/pagination"
image: "https://nov18-prod-sg.movespot.fyi/_og/d/c_Ocean.takumi,title_Pagination,description_~UGFnZSB0aHJvdWdoIGxhcmdlIHJlc3VsdCBzZXRzIHdpdGggY3Vyc29ycywgd2l0aG91dCBza2lwcGluZyBvciByZXBlYXRpbmcgaXRlbXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNDQjUzMjQifX19,p_Ii9ndWlkZXMvcGFnaW5hdGlvbiI,s_hERylDwJ_ig3_ztj.png"
---

# Pagination

Page through large result sets with cursors, without skipping or repeating items.

## [Cursor pagination](#cursor-pagination)

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

```json
{
  "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:

```bash
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](#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](#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](#walk-every-page)

```javascript
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](https://nov18-prod-sg.movespot.fyi/guides/rate-limits).

## [Next steps](#next-steps)

### Make your first request

Walk through a complete request and response, headers to status codes.

<https://nov18-prod-sg.movespot.fyi/guides/first-request>

### Webhooks

Get notified when resources change instead of polling.

<https://nov18-prod-sg.movespot.fyi/guides/webhooks>

### Rate limits

Read your remaining quota and back off before you hit `429`.

<https://nov18-prod-sg.movespot.fyi/guides/rate-limits>