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:

{
    "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:

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:

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>'
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.

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:

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.