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

# Pagination

> Page through a list with cursors.

A list route returns one page at a time, in this shape:

```json theme={null}
{
  "data": [
    { "id": "0199a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b", "type": "CASH", "amountCents": 10000 }
  ],
  "hasMore": true,
  "nextCursor": "v1.eyJpZCI6IjAxOTk...",
  "prevCursor": "v1.eyJpZCI6IjAxOTk..."
}
```

| Field        | Meaning                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------- |
| `data`       | The records on this page. Each list's order is stated in its **API Reference** description. |
| `hasMore`    | Whether more records exist beyond this page in the direction you are reading.               |
| `nextCursor` | Send it as `startingAfter` to read the page after this one. Absent when the page is empty.  |
| `prevCursor` | Send it as `endingBefore` to read the page before this one. Absent when the page is empty.  |

## Parameters

| Parameter       | Meaning                                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`         | Records per page, 1 to 100. Defaults to 50.                                                                                                                                                   |
| `startingAfter` | A `nextCursor` from a previous page.                                                                                                                                                          |
| `endingBefore`  | A `prevCursor` from a previous page.                                                                                                                                                          |
| `orderBy`       | Fields to sort by, when the list offers it, each written `field:ASC` or `field:DESC` and separated by commas. The **API Reference** lists each route's sortable fields and its default order. |

A request may carry `startingAfter` or `endingBefore`, not both.

## Reading a whole list

1. Request the first page with no cursor.
2. If `hasMore` is true, request the next page with `startingAfter` set to the `nextCursor` you received.
3. Repeat until `hasMore` is false.

```bash theme={null}
curl "https://app.synthetic.ai/api/v1/payments?limit=100" \
  -H "Authorization: Bearer <key>"

curl "https://app.synthetic.ai/api/v1/payments?limit=100&startingAfter=<nextCursor>" \
  -H "Authorization: Bearer <key>"
```

## Filters and order

A list route may accept filters, listed in the **API Reference** for that route. Boolean filters take the words `true` and `false`.

A cursor is bound to the filters and the `orderBy` it was issued under. Sending it back with different filters or a different order returns `400` rather than a page that silently skips or repeats records. To change either, start again from the first page with no cursor.

Cursors are opaque. Store and return them unchanged, and do not build them yourself.