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

# Pagination

> Navigate large result sets with cursor-based pagination.

## Overview

List endpoints return paginated responses using cursor-based pagination. This approach provides stable results even when data changes between requests.

## How it works

### Query parameters

| Parameter   | Type    | Default      | Description                                 |
| ----------- | ------- | ------------ | ------------------------------------------- |
| `limit`     | integer | `10`         | Maximum number of items to return per page  |
| `cursor`    | string  | —            | Cursor returned from a previous response    |
| `direction` | string  | —            | Pagination direction: `NEXT` or `PREVIOUS`  |
| `sortOrder` | string  | `DESCENDING` | Sort direction: `ASCENDING` or `DESCENDING` |

### Response structure

Every list response includes a `meta` object alongside the `data` array:

```json theme={"theme":"tokyo-night"}
{
  "data": [
    { "id": "acc_001", "type": "CHECKING" },
    { "id": "acc_002", "type": "SAVING" }
  ],
  "meta": {
    "previousCursor": null,
    "nextCursor": "eyJpZCI6ImFjY18wMDIifQ",
    "total": 45
  }
}
```

| Field            | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `previousCursor` | Cursor to fetch the previous page. `null` on the first page. |
| `nextCursor`     | Cursor to fetch the next page. `null` on the last page.      |
| `total`          | Number of items returned in the current page.                |

## Examples

**First page:**

```bash theme={"theme":"tokyo-night"}
curl --request GET \
  --url 'https://api.sandbox.tracefinance.com/v1/accounts?limit=10' \
  --header 'Authorization: Bearer <token>'
```

**Next page** — pass the `nextCursor` value as `cursor`:

```bash theme={"theme":"tokyo-night"}
curl --request GET \
  --url 'https://api.sandbox.tracefinance.com/v1/accounts?limit=10&cursor=eyJpZCI6ImFjY18wMDIifQ' \
  --header 'Authorization: Bearer <token>'
```

**Iterating through all pages:**

```python theme={"theme":"tokyo-night"}
cursor = None

while True:
    params = {"limit": 10}
    if cursor:
        params["cursor"] = cursor

    response = client.get("/accounts", params=params)
    data = response.json()

    for item in data["data"]:
        process(item)

    cursor = data["meta"]["nextCursor"]
    if cursor is None:
        break
```