> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# Pagination

Paginated list endpoints return one page at a time. When a response includes `nextCursor`, pass it back to read the next page. An absent or `null` cursor marks the end. The API Reference lists the parameters supported by each endpoint.

## Parameters

| Parameter | Type | What it does |
|-----------|------|--------------|
| `limit` | integer | Items per page. Default 50. Valid values are 1 through 100. |
| `cursor` | string | The `nextCursor` from your last response. Leave it off for the first page. |
| `withCount` | boolean | Where supported, set `true` to also get a total `count` of matching items. Off by default. |

## Response

```json
{
  "data": [
    { "id": "txn_8f2a1c9e", "type": "Invoice", "amount": { "amount": 152900, "currency": "USD" } }
  ],
  "nextCursor": "eyJpZCI6InR4bl84ZjJhMWM5ZSJ9"
}
```

`data` holds at most `limit` items. On endpoints that support it, `withCount=true` adds a `count` of all matching items.

## Traverse

Request the first page, then pass each `nextCursor` back as `cursor`.

```bash
# First page
curl "https://next-api.saturation.io/v1/transactions?projectId=prj_a1&limit=100" \
  -H "Authorization: Bearer $SATURATION_TOKEN"

# Next page: pass the previous nextCursor back as cursor
curl "https://next-api.saturation.io/v1/transactions?projectId=prj_a1&limit=100&cursor=eyJpZCI6InR4bl84ZjJhMWM5ZSJ9" \
  -H "Authorization: Bearer $SATURATION_TOKEN"
```

The cursor is opaque. Keep the request's filters and sort identical while you page. An incompatible cursor returns `400 cursor_invalid`. See [Errors](/errors.md).

Pagination uses cursors rather than page numbers.

## Next

- [Rate limits](/rate-limits.md): how fast you can page through a large collection.
- [Errors](/errors.md): the response when a request fails.