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

# Pagination

Most of our API endpoints that return lists of objects support the ability to paginate through records. Our API uses cursor based
pagination, which breaks down a large response into smaller responses called **pages**, that the caller can step through to read
all of the data.

Our cursor-based pagination gives you a deterministic result, so no records are skipped between pages. Cursor-based pagination is
typically more performant than other approaches, since there is less data to load when navigating between pages.

### Paginating through records

When pagination is available, the API will respond with a payload similar to:

```json theme={null}
{
    "next_page_token": "gAAAAABlSRfLM0b-MzI3NmM0N0MmLWJkOTQtYjkxZTRkMzkyNTE3==",
    "prev_page_token": "gAAAAABlSRfLFpdvYTM3OTQ0Y0OlLWI0YzYtNmYxMjU3N2NmMDk2==",
    "records": []
}
```

As you can see, there are two tokens `next_page_token` and `prev_page_token`. As their name suggest, the `next_page_token` is
used to request the next page, and the `prev_page_token` is used to retrieve the previous page. In addition, when there isn't
a next page token or a previous page token, the value for either token will be `null`.

To request the next or previous page, you must pass the url parameter `page_token` with the `next_page_token` value assigned to
it. For example, here is a request to get the next page of Ledgers:

```Shell theme={null}
curl --request get \
--url 'https://api.sandbox.teal.dev/v0/ledgers?page_token=<next_page_token>' \
--header 'Authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>'
```

And here is the command to request the previous page:

```Shell theme={null}
curl --request get \
--url 'https://api.sandbox.teal.dev/v0/ledgers?page_token=<prev_page_token>' \
--header 'Authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>'
```

<Note> Keep in mind that the `page_token` url parameter is optional. If the value is not specified, the first page will be returned
by the API. </Note>

### Page sizes

By default, the API returns 50 records per page, with a maxiumum value of 100 records per page. This value is configurable by
passing the `limit` attribute as a url parameter. For example:

```Shell theme={null}
curl --request get \
--url 'https://api.sandbox.teal.dev/v0/ledgers?page_token=<next_page_token>&limit=100' \
--header 'Authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>'
```

The request above will return 100 records for the next page.