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

Method Description
Offset-based Divides the results into pages by indicating the number of items per page.
Cursor-based Uses 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.

Attribute Description
pageNumber The number of the page to retrieve.
pageCount The number of objects per page.
sortBy The object attribute to sort the list with (e.g., creationDate, modifiedDate, etc.). Differs for each endpoint.
sortOrder The order you want to sort the list. Either:
  • DESC (default) for a descending order
  • ASC for a 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:

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

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:

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

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

Attribute string Description
prev string Pointer for the previous page. null if on the first page.
current string Pointer for the current page.
next string Pointer 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.

Attribute Description
cursor The 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.

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:

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

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
Updated on: 5/23/2024, 8:00:33 AM