Skip to content

Pagination

Pagination consists in breaking down the list of returned objects into subsets that you can then navigate.

Treezor offers 2 methods to paginate API responses, depending on the endpoints.

MethodDescription
Offset-basedDivides the results into pages by indicating the number of items per page.
Cursor-basedUses a cursor to mark the last item in each page.

Offset-based pagination

Parameters

Endpoints supporting offset pagination rely on the following query parameters for pagination.

AttributeDescription
pageNumberThe number of the page to retrieve.
pageCountThe number of objects per page.
sortByThe object attribute to sort the list with (e.g., creationDate, modifiedDate, etc.). Differs for each endpoint.
sortOrderThe order you want to sort the list. Either:
  • DESC (default) for a descending order
  • ASC for an ascending order

Examples

Let's retrieve the list of transfers for a specific wallet with the following pagination parameters:

  • 1st page (pageNumber=1)
  • 30 objects (pageCount=30)
  • Sorted by creation date (sortBy=creationDate)
  • In chronological order, so that the most recently created is displayed last (sortOrder=ASC)

You need to make the following request:

bash
curl -X GET {baseUrl}/v1/transfers?pageNumber=1&pageCount=30&sortBy=creationDate&sortOrder=ASC&walletId={{walletId}} \
	 --header 'Authorization: Bearer {accessToken}'

Returns an array of 30 objects (or less, in the last page).

json
[
	{
		"walletId": 28749,
		"createdDate": "2019-03-10T08:05:10-00:00",
		[...]
	},
	{
		"walletId": 92758,
		"createdDate": "2020-08-25T07:08:20-00:00",
		[...]
	},
	{
		"walletId": 57820,
		"createdDate": "2021-02-03T07:09:33-00:00",
		[...]
	},
	[...] // 27 more objects hidden
]

Now, let's retrieve the same list of transfers for the wallet, but with the following pagination parameters instead:

  • 5th page (pageNumber=5)
  • 50 objects (pageCount=50)
  • Sorted by amount (sortBy=amount)
  • In descending order, so that the highest amount is displayed first (sortOrder=DESC)

You need to make the following request:

bash
curl -X GET {baseUrl}/v1/transfers?pageNumber=5&pageCount=50&sortBy=amount&sortOrder=DESC&walletId={{walletId}} \
	 --header 'Authorization: Bearer {accessToken}'

Returns an array of 50 objects (or less, in the last page).

json
[
	{
		"walletId": 82749,
		"amount": 4298,
		[...]
	},
	{
		"walletId": 10855,
		"amount": 2310,
		[...]
	},
	{
		"walletId": 42187,
		"amount": 150,
		[...]
	},
	[...] // 47 more objects hidden
]

Supported endpoints

Usually, endpoints with a v1 prefix in their path and used to retrieve a list of objects support offset pagination.

List of endpoints supporting offset pagination

Cursor-based pagination

Cursor-based pagination works by returning a pointer to a specific item in the dataset. Then, you specify one of the returned cursors in your next request to navigate the datasets.

As opposed to offset pagination, cursor-based pagination is not optional. As soon as you make your request to retrieve your list of objects, the results will be paginated and the first page will be displayed by default.

The number of objects returned varies depending on each endpoint. Most endpoints returns 50 objects.

Cursor object

API Responses for endpoints supporting cursors will include the cursor object.

json
"cursor": {
    "prev": null,
    "current": "356a192b7913b04c54574d18c28d46e6395428ab",
    "next": "da4b9237bacccdf19c0760cab7aec4a8359010b0"
}
AttributestringDescription
prevstringPointer for the previous page. null if on the first page.
currentstringPointer for the current page.
nextstringPointer for the next page. null if on the last page.

If there is no adjacent operation, the next attribute will be valued to null. The current attribute can be cached and used later to only retrieve new operations.

Parameters

Endpoints supporting cursor-based pagination rely on the cursor query parameters for pagination. The size of the subset (number of objects returned) varies depending on each endpoint. Most endpoints returns 50 objects.

AttributeDescription
cursorThe desired starting position for your next subset of objects.

Example

When initially using the {baseUrl}/core-connect/operations, the response returned 50 operations and included the cursor object.

json
"cursor": {
    "prev": null,
    "current": "356a192b7913b04c54574d18c28d46e6395428ab",
    "next": "da4b9237bacccdf19c0760cab7aec4a8359010b0"
}

Since there is no prev value, we know we are on the first subset of responses. To navigate to the next subset, the next value must be used for the cursor query parameter, as in the following request:

bash
curl -X GET  {baseUrl}/core-connect/operations?walletId={walletId}&dateFrom={dateFrom}&dateTo={dateTo}&cursor=da4b9237bacccdf19c0760cab7aec4a8359010b0 \
	--header 'Authorization: Bearer {accessToken}'

This returns the next subset of Operations objects, which will include the cursor object again:

json
"cursor": {
    "prev": "e99a18c428cb38d5f260853678922e03abd83395",
    "current": "da4b9237bacccdf19c0760cab7aec4a8359010b0",
    "next": null
}

In this example, the next value is null, indicating that we are on the last subset.

Supported endpoints

Usually, endpoints with a core-connect prefix in their path and used to retrieve a list of objects support cursor-based pagination. Some v1 endpoints have been migrated to this pagination system too.

List of endpoints supporting cursor pagination