Skip to main content

Paginating through any endpoint

Most endpoints that return lists support consistent pagination parameters and metadata. Use these controls to page through results without missing data or fetching more than you need.

Query parameters​

  • limit – number of items to return in a single request. Defaults vary per endpoint.
  • page – zero-based index of the page to fetch.
  • order – when supported, choose ASC or DESC to control sort order.

These parameters behave the same across endpoints such as /breeds, /images/search, /votes, /favourites and /pets. Combine them with any other filters that an endpoint accepts. The content endpoints /facts and /health-tips use offset (number of items to skip) in place of page.

Response headers​

Every paginated response includes the following HTTP headers:

  • pagination-count – total number of items that match the filters you supplied.
  • pagination-page – the zero-based page index that was returned.
  • pagination-limit – the limit that was applied to the response.

Together, these headers let you calculate the total number of available pages and implement client-side pagination UI.

Example​

The breeds endpoint uses the same pagination structure:

curl --location 'https://api.thecatapi.com/v1/breeds?limit=10&page=2&order=ASC' \
  --header 'x-api-key: YOUR-API-KEY'

Relevant response headers:

pagination-count: 107
pagination-page: 2
pagination-limit: 10

Use limit and page together to walk through every cat breed.