# Pagination

REST API endpoints that potentially may return an unlimited number of items are paginated.

## Requests

In addition to the endpoint-specific parameters, endpoints that return paginated responses accept the following pagination parameters to control the page and number of items per page correspondingly:

| Parameter   | Type  | Default | Description              |
| ----------- | ----- | ------: | ------------------------ |
| `page`      | `int` |     `1` | Page number              |
| `page_size` | `int` |    `10` | Number of items per page |

The maximum number of items per page is `250`.

## Responses

Paginated responses contain two additional properties providing information on the total number of items and the total number of pages:

| Parameter    | Type  | Description           |
| ------------ | ----- | --------------------- |
| `item_count` | `int` | Total number of items |
| `page_count` | `int` | Total number of pages |

## Example

Get the second page of accounts with `25` items per page:

```bash
curl -X 'GET' \
  'https://api.testnet.cspr.cloud/accounts?page=2&page_size=25' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'
```

```json
{
  "data": [
    {
      "account_hash": "37f304a6632b214eacc45b85f6a45759194ea69f6684da0bca42d60e42ac8e12",
      "balance": "3050076259180",
      "main_purse_uref": "uref-692b5b8afcad47b0dee74962540a01ea1402fc0c9c84d9474e5766775373795c-007",
      "public_key": "019aa4adcd6f58f92eb4c98c0245e5d86b61de4919245c23ae9e906a6df5d41b0c"
    },
    {
      "account_hash": "7894d8458c82388f6d276c07c1c52033ac37b175fa722b9cc40e7a0157ce17fc",
      "balance": "252442325961483",
      "main_purse_uref": "uref-c4afe0fb020ebcdc940289d759499ff5fb87e999567e4d61d836d70bfad20a55-007",
      "public_key": "0145fb72c75e1b459839555d70356a5e6172e706efa204d86c86050e2f7878960f"
    },
    ...
    {
      "account_hash": "eb108759cf29b5d1ce6a311989890170d94bb98e06e4097e4ee20c18d6bf4f16",
      "balance": "80331298738010",
      "main_purse_uref": "uref-fd73e477cbbeb134ebb7fee8ccb423c8d45c88e23bd82d2d1104fc7f34f3a27b-007",
      "public_key": "0154d4c09bcae885fdd3dc0bf8ac7fa23ae281baf60a5b352b1ff0b505a65e1285"
    }
  ],
  "item_count": 63584,
  "page_count": 2544
}
```

## Traversing results

When making an API request to an endpoint that returns paginated data, you usually don't receive all of the results in a single response. To traverse the data, you need to increment the page number in your requests until you collect all the required items. When doing so, note the [rate limits](https://docs.cspr.cloud/documentation/overview/rate-limits-and-quotas). Setting the number of items per page to its maximum value of `250` will minimize the chances of being rate-limited for most of the use cases.

Note that if new objects are added to the list of items being paginated, the contents of each page will change.