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:

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

​

Page sizes

By default, the API returns 50 records per page, with a maxiumum value of 1000 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.