+++
title = "API Result Pagination"
weight = 100
updated = 2026-10-13
aliases = ["/docs/api-result-pagination.html", "/docs/bonsai-api/reference/api-result-pagination/", "/docs/api/reference/api-result-pagination/"]

[extra]
nav_title = "API Result Pagination"
weight = 10
+++

{{ legacy_api_notice() }}

All API responses which support pagination will include a top level pagination fragment in the JSON response body.

[Viewing all clusters](@/docs/api/legacy/endpoints/cluster-api/index.md#view-all-clusters) is the only paginated call. The Plans, Spaces and Releases APIs return every result in one response.

## Pagination Query Parameters

Paginated calls recognize the following request parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>page</td><td>The page number, starting at 1. Defaults to 1.</td>
    </tr>
    <tr>
      <td>size</td><td>The number of results on each page, from 1 to 1000. Defaults to 1000. A larger value is treated as 1000, and a value below 1 as 1.</td>
    </tr>
  </tbody>
</table>

## Pagination Response Fragment

All API responses which support pagination will include a top level pagination fragment in the JSON response body, which looks like:

```javascript
"pagination": {
 "page_number": 1,
 "page_size": 100,
 "total_records": 255
}
```

`page_size` is the page size used, after the limits above, and `total_records` counts every result across all pages. With the above information, you can infer how many pages there are and iterate until the list is exhausted.