# Pagination (/standards/pagination)



The public API uses cursor-based pagination for paginated list endpoints.

Cursor-based pagination is preferred because it is:

* Stable when new records are created while a client is paging through results.
* Efficient for large result sets.
* Familiar to API consumers who work with external APIs such as Stripe, GitHub, and Shopify.

## Request Parameters [#request-parameters]

Paginated endpoints use these query parameters:

| Parameter | Type      | Description                                                                                 |
| --------- | --------- | ------------------------------------------------------------------------------------------- |
| `limit`   | `integer` | Number of items to return. Default: `25`. Maximum: `100`.                                   |
| `cursor`  | `string`  | Opaque cursor returned by the previous page. Omit this parameter to request the first page. |

Clients should treat `cursor` as an opaque token and should not attempt to parse or construct it.

## Response Shape [#response-shape]

Paginated endpoints return a response shaped like this:

```json
{
  "data": [],
  "has_more": true,
  "next_cursor": "eyJpZCI6Li4u"
}
```

### Fields [#fields]

| Field         | Type             | Description                                                                           |
| ------------- | ---------------- | ------------------------------------------------------------------------------------- |
| `data`        | `array`          | The items in the current page.                                                        |
| `has_more`    | `boolean`        | Whether another page is available after this one.                                     |
| `next_cursor` | `string \| null` | Cursor to pass on the next request. Omitted or `null` when there are no more results. |

## Client Guidance [#client-guidance]

* Omit `cursor` on the first request.
* To fetch the next page, pass the `next_cursor` value returned by the previous response.
* Stop paging when `has_more` is `false`.
* Do not assume cursors are stable forever. Use them as short-lived continuation tokens.

## Design Notes [#design-notes]

* Total counts are not included in public pagination responses.
* Cursor-based pagination is the standard for the public API even if other interfaces use a different pagination model.
* Endpoint-specific filtering and sorting rules will be documented alongside each operation in the API reference.