> ## Documentation Index
> Fetch the complete documentation index at: https://www.myhamlet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page through list endpoints with opaque cursors.

All list endpoints are **cursor-paginated** and ordered by `updated_at` ascending
(oldest first), which makes them safe to page through and to
[sync incrementally](/incremental-sync).

## The list envelope

Every list response is a `data` array plus a `next_cursor`:

```json theme={null}
{
  "data": [ /* … items … */ ],
  "next_cursor": "eyJ1IjoiMjAyNi0wNS0wMSAxODoyMjoxMCIsImkiOjQyfQ"
}
```

* `next_cursor` is an **opaque** string — pass it back unchanged as the `cursor` query
  parameter to fetch the next page. Don't parse or construct it yourself.
* `next_cursor` is `null` on the last page.

## Paging through results

Control page size with `per_page` (1–100, default 50). Pass the previous response's
`next_cursor` as `cursor` until it comes back `null`:

```bash theme={null}
# First page
curl "https://api.myhamlet.com/v1/locations?per_page=50" \
  -H "Authorization: Bearer hmlt_your_api_key"

# Next page — feed back the previous next_cursor
curl "https://api.myhamlet.com/v1/locations?per_page=50&cursor=eyJ1IjoiMjAyNi0wNS0wMSAxODoyMjoxMCIsImkiOjQyfQ" \
  -H "Authorization: Bearer hmlt_your_api_key"
```

A simple loop:

```python theme={null}
import requests

base = "https://api.myhamlet.com/v1/locations"
headers = {"Authorization": "Bearer hmlt_your_api_key"}
cursor, results = None, []

while True:
    params = {"per_page": 100}
    if cursor:
        params["cursor"] = cursor
    page = requests.get(base, headers=headers, params=params).json()
    results.extend(page["data"])
    cursor = page["next_cursor"]
    if cursor is None:
        break
```

To pull only the records that changed since your last run, combine this with
`updated_since` — see [Incremental sync](/incremental-sync).