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:

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'

{
  "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. 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.