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