# Pagination (/developers/api/pagination)



All list endpoints use page-based pagination with consistent request parameters and response structure.

## Request Parameters [#request-parameters]

Include these query parameters on any list endpoint:

<TypeTable
  type="{
  &#x22;page&#x22;: { type: &#x22;integer&#x22;, description: <>{&#x22;The page number to retrieve (starting from 1).&#x22;}</>, default: &#x22;1&#x22; },
  &#x22;limit&#x22;: { type: &#x22;integer&#x22;, description: <>{&#x22;The number of items to return per page (minimum 1, maximum 100).&#x22;}</>, default: &#x22;25&#x22; },
}"
/>

## Response Structure [#response-structure]

List endpoints return an object with `items` and `pagination`:

```json
{
  "ok": true,
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "limit": 25,
      "total": 142,
      "totalPages": 6
    }
  }
}
```

## Pagination Object [#pagination-object]

<TypeTable
  type="{
  &#x22;page&#x22;: { type: &#x22;integer&#x22;, description: <>{&#x22;The current page number.&#x22;}</>, required: true },
  &#x22;limit&#x22;: { type: &#x22;integer&#x22;, description: <>{&#x22;The number of items per page.&#x22;}</>, required: true },
  &#x22;total&#x22;: { type: &#x22;integer&#x22;, description: <>{&#x22;The total number of items across all pages.&#x22;}</>, required: true },
  &#x22;totalPages&#x22;: { type: &#x22;integer&#x22;, description: <>{&#x22;The total number of pages.&#x22;}</>, required: true },
}"
/>

## Best Practices [#best-practices]

1. Use `page` and `limit` query parameters when making requests to list endpoints.
2. Respect the maximum `limit` of 100 items per page.
3. Check `totalPages` to know when you've reached the last page.
4. An empty `items` array with `total: 0` means no results matched your query.

## Limitations [#limitations]

* The maximum allowed `limit` is 100 items per page.
* If a `limit` greater than 100 is requested, the API will return a validation error.
* Default `limit` varies by resource (20 or 25) but all cap at 100.