> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/getting-started/pagination.md).

# Pagination

List endpoints return paginated results to improve performance. You control pagination using query parameters:

| Parameter  | Default | Maximum | Description           |
| ---------- | ------- | ------- | --------------------- |
| `page`     | 1       | -       | Page number (1-based) |
| `per_page` | 50      | 100     | Items per page        |

**Example request:**

```
GET /v2/customers?page=2&per_page=25
```

**Response format:**

```json
{
  "data": [
    { "id": "cus_123", "email": "john@example.com", ... },
    { "id": "cus_124", "email": "jane@example.com", ... }
  ],
  "meta": {
    "pagination": {
      "page": 2,
      "page_size": 25,
      "total_count": 150,
      "total_pages": 6,
      "has_more": true
    }
  }
}
```

Note that `pagination` is nested inside `meta`, not at the top level.

The `meta.pagination` object provides:

* `page`: Current page number
* `page_size`: Items per page (same as the `per_page` parameter)
* `total_count`: Total number of items across all pages
* `total_pages`: Total number of pages
* `has_more`: Whether another page follows this one

`has_more` is the value to loop on. Paging until a request returns an empty `data` array works, but costs one extra request per resource per run, and every request counts against your quota.

Pagination is offset-based. There is no cursor, and no `next` link in the envelope — advance by incrementing `page`.
