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

# API pagination

> Page through lists with cursors, filter by date, and sync changes into your database.

Every list endpoint pages with cursors. Pass the `next_cursor` you got back as `starting_after` until `has_more` is `false`.

Your codesync jobTolt/v2/customers*1*GET ?limit=100*2*next\_cursor: cur\_WyIy…*3*GET ?starting\_after=cur\_WyIy…*4*has\_more: false

## Parameters

| Parameter | Default | Description |
| - | - | - |
| `limit` | `10` | Items per page, `1` to `100` |
| `sort` | `created_at` | `created_at` or `updated_at` |
| `order` | `desc` | `asc` or `desc` |
| `starting_after` | | A `next_cursor`. Returns the items after it |
| `ending_before` | | A `prev_cursor`. Returns the items before it (paging backwards) |
| `created_after` / `updated_after` | | ISO 8601 with offset. Inclusive |
| `created_before` / `updated_before` | | ISO 8601 with offset. Exclusive |

Responses add `has_more`, `next_cursor` and `prev_cursor`. Cursors are opaque `cur_...` strings. Don't combine `starting_after` and `ending_before`, and keep the same filters and sort from page to page: a cursor only works with the `sort` it came from. With `sort=created_at` you can also pass an item id as the position.

## Page through everything

```ts TypeScript theme={"system"}
import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

for await (const customer of await tolt.customers.list({ limit: 100 })) {
  console.log(customer.id);
}
```

```python Python theme={"system"}
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

for customer in client.customers.list(limit=100):
    print(customer.id)
```

```bash cURL theme={"system"}
curl -G https://platform.tolt.com/v2/customers \
  -d limit=100 \
  -d starting_after=cur_WyIyMDI2LTA5LTE0VDA5OjEyOjQ0LjAwMFoiXQ \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

A cursor that isn't valid for the list returns `400` with `invalid_cursor`.

## Sync changes

To mirror Tolt into your database, read by `updated_at` in a fixed window and upsert by `id`:

```bash theme={"system"}
curl -G https://platform.tolt.com/v2/commissions \
  -d sort=updated_at \
  -d order=asc \
  -d updated_after=2026-09-01T00:00:00Z \
  -d updated_before=2026-09-01T01:00:00Z \
  -d limit=100 \
  -H "Authorization: Bearer $TOLT_API_KEY"
```

Page until `has_more` is `false`, then use this run's `updated_before` as the next run's `updated_after`, so windows don't leave a gap. To absorb clock drift, start each window a few minutes earlier and upsert by `id`, as in [Sync your data](/guides/sync-data).

> **Why a fixed window with a lag**
>
> A row can become visible slightly after the `updated_at` it carries. Set `updated_before` a few minutes behind Tolt's clock (read the `Date` response header, not your own clock) so every row in the window has committed. A fixed upper bound also keeps the window from moving while you page. Upserting by `id` absorbs repeats at the inclusive boundary.

## Report breakdowns use offsets

`GET /v2/reports/partners` and `GET /v2/reports/links` sort by a metric, so they page with `limit` and `offset` (`0` to `10000`) instead of cursors. `sort` is `revenue`, `commissions`, `clicks` or `customers`.

```bash theme={"system"}
curl -G https://platform.tolt.com/v2/reports/partners \
  -d sort=revenue \
  -d limit=20 \
  -d offset=20 \
  -H "Authorization: Bearer $TOLT_API_KEY"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.