***

title: Pagination
subtitle: How to paginate through list endpoints
slug: api-guides/pagination
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/api-guides/llms.txt. For full documentation content, see https://docs.prolifi.io/api-guides/llms-full.txt.

## Offset-based pagination

All list endpoints (`GET /plans`, `GET /customers`, `GET /subscriptions`, `GET /invoices`) use offset-based pagination with two query parameters:

| Parameter | Type    | Default | Description                                      |
| --------- | ------- | ------- | ------------------------------------------------ |
| `limit`   | integer | 20      | Maximum items to return per page (1-100)         |
| `offset`  | integer | 0       | Number of items to skip before returning results |

## Request example

```bash
# First page (items 0-19)
curl "https://api.prolifi.co/api/v1/public/customers?limit=20&offset=0" \
  -H "Authorization: Bearer sk_test_..."

# Second page (items 20-39)
curl "https://api.prolifi.co/api/v1/public/customers?limit=20&offset=20" \
  -H "Authorization: Bearer sk_test_..."
```

## Response format

Every paginated response includes a `pagination` object alongside the `data` array:

```json
{
  "data": [
    { "id": "...", "email": "user1@example.com", "..." : "..." },
    { "id": "...", "email": "user2@example.com", "..." : "..." }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

| Field      | Type    | Description                                        |
| ---------- | ------- | -------------------------------------------------- |
| `total`    | integer | Total number of items matching the query           |
| `limit`    | integer | Items per page (echoed from request)               |
| `offset`   | integer | Current offset (echoed from request)               |
| `has_more` | boolean | `true` if more items exist beyond the current page |

## Iterating through all pages

To retrieve all results, increment `offset` by `limit` on each request until `has_more` is `false`:

```python
offset = 0
limit = 100
all_items = []

while True:
    response = api.get("/customers", params={"limit": limit, "offset": offset})
    all_items.extend(response["data"])

    if not response["pagination"]["has_more"]:
        break

    offset += limit
```