Some endpoints may return a large number of results, so we provide pagination to help you request only a subset of the results at a time.

Types of pagination

There are two types of pagination we use underneath:

  • Page-based pagination: This method uses a paging parameter to indicate the starting point of records to return.
  • Cursor-based pagination: This method utilizes a unique identifier to determine the position in the data set.

There are different advantages and disadvantages to each method, but performance wise cursor-based pagination is generally more efficient.

Currently, most of the endpoints are offset-based, but we are working on migrating all of them to be cursor-based. To make it transparent to you, we have standardized pagination in the response object to work with both methods.

Pagination in responses

When an endpoint supports pagination, the response will include a pagination object with the following properties:

  • next: The URL to the next page. This property will be omitted if the result set is empty or if the next page has no results.
  • previous: The URL to the previous page. This property will be omitted if the result set is empty or if there’s no previous page.
  • first: The URL to the first page. This property will be omitted if the result set is empty.

Here are a few examples of how the pagination object may look like in the response:

{
  "pagination": {
    "first": "https://api.enterprise.uphold.com/core/transactions?page=1&perPage=10",
    "next": "https://api.enterprise.uphold.com/core/transactions?page=2&perPage=10",
  }
}
Make sure to use these URLs when requesting pages instead of hardcoding them, otherwise your implementation may break as we migrate to cursor-based pagination in the future.

Number of results per page

To control how many results are returned per page, you can use the perPage query parameter. For example, to request 100 results per page, you would add ?perPage=100 to the URL.

The perPage parameter will automatically be included in the URLs in the pagination object, so you don’t need to worry about it when following the pagination links.