> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Paginate Uphold REST API list responses using page-based and cursor-based pagination. Includes parameters, response metadata, and best-practice usage.

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

## Types of pagination

There are two types of pagination used 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 they are being migrated to cursor-based.
To make this transparent to you, the pagination response object is standardized 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:

<CodeGroup>
  ```json On first page theme={null}
  {
    "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",
    }
  }
  ```

  ```json On second page theme={null}
  {
    "pagination": {
      "first": "https://api.enterprise.uphold.com/core/transactions?page=1&perPage=10",
      "next": "https://api.enterprise.uphold.com/core/transactions?page=3&perPage=10",
      "previous": "https://api.enterprise.uphold.com/core/transactions?page=1&perPage=10",
    }
  }
  ```

  ```json On last page theme={null}
  {
    "pagination": {
      "first": "https://api.enterprise.uphold.com/core/transactions?page=1&perPage=10",
      "previous": "https://api.enterprise.uphold.com/core/transactions?page=10&perPage=10",
    }
  }
  ```
</CodeGroup>

<Tip>Make sure to use these URLs when requesting pages instead of hardcoding them, otherwise your implementation may break as endpoints migrate to cursor-based pagination in the future.</Tip>

## 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` query parameter 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.