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

# Pagination

Retrieve large collections page by page with cursor pagination

Every OCTO list endpoint returns results in pages of up to 100 records. To read a whole collection, follow the `Octo-Next-Page` response header from one request to the next until it is no longer returned.

{% hint style="warning" %}
**Numbered pages are no longer supported.** Sending a numeric `page` (for example `page=1`) or the old `perPage` parameter returns `400 Bad Request`. Requests without `page` return the first page only, not the whole collection. See [Migrating from numbered pages](#migrating-from-numbered-pages).
{% endhint %}

## Endpoints

Cursor pagination applies to every OCTO collection endpoint, including:

* `GET /products`
* `GET /bookings`
* `GET /orders` (with [`octo/cart`](https://docs.ventrata.com/capabilities/cart.md))
* `GET /webhooks` (with [`octo/webhooks`](https://docs.ventrata.com/capabilities/webhooks.md))
* Notification subscriptions (with [`octo/notifications`](https://docs.ventrata.com/capabilities/notifications.md))

## Parameters

| Parameter | Where | Description                                                                                          |
| --------- | ----- | ---------------------------------------------------------------------------------------------------- |
| `limit`   | Query | Maximum number of records to return, from `1` to `100`. Defaults to `100`. Send it on every request. |
| `page`    | Query | The cursor from the previous response's `Octo-Next-Page` header. Omit it on the first request.       |

| Response header  | Description                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `Octo-Next-Page` | An opaque cursor for the next page. Absent on the last page or when there are no results. |

The response body keeps its usual shape: an array of records.

## How to paginate

{% stepper %}
{% step %}

### Make the first request without `page`

Keep your usual filters, headers and capabilities.

```http
GET /octo/products?limit=100
Authorization: Bearer YOUR_API_KEY
Octo-Capabilities: octo/pricing
```

{% endstep %}

{% step %}

### Read `Octo-Next-Page`

```http
HTTP/1.1 200 OK
Content-Type: application/json
Octo-Next-Page: <opaque-cursor>
```

{% endstep %}

{% step %}

### Send it back as `page`

Use the exact value, with the same endpoint, filters, ordering, `limit`, authentication and capabilities. Let your HTTP client URL-encode it.

```http
GET /octo/products?limit=100&page=<opaque-cursor>
```

{% endstep %}

{% step %}

### Repeat until `Octo-Next-Page` is absent

When the header is missing, you have the whole collection.
{% endstep %}
{% endstepper %}

### Example

The same loop works for products, bookings, orders and webhooks.

```python
import os
import requests

url = "https://api.ventrata.com/octo/products"
headers = {
    "Authorization": f"Bearer {os.environ['OCTO_API_TOKEN']}",
    "Octo-Capabilities": "",  # keep the capabilities your integration already uses
}
params = {"limit": 100}  # keep your existing filters here; never send perPage

while True:
    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    records = response.json()
    # process or store this batch of records

    cursor = response.headers.get("Octo-Next-Page")
    if not cursor:
        break
    params["page"] = cursor
```

## Rules

* **Treat the cursor as opaque.** Don't decode, modify, construct or increment it.
* **Fetch pages in order.** Each cursor comes from the previous response, so pages can't be requested in parallel.
* **Keep the request the same while traversing.** Changing filters or ordering starts a new traversal. Changing `limit` between pages is allowed.
* **There is no total count.** Use the absence of `Octo-Next-Page` as the stopping condition.
* **Results are not a snapshot.** A record that changes while you traverse can move between pages. Syncs that must not miss changes should also use [Webhooks](https://docs.ventrata.com/capabilities/webhooks.md).
* **Browser clients** can read `Octo-Next-Page`; it is exposed to cross-origin requests.

## Migrating from numbered pages

| Before                                        | Now                                                                                                                  |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `perPage=100`                                 | `limit=100`                                                                                                          |
| `page=1`, `page=2`, …                         | No `page` on the first request, then `page=<value of Octo-Next-Page>`                                                |
| Stop when you reach `Octo-Total-Pages`        | Stop when `Octo-Next-Page` is absent. `Octo-Total-Pages` is no longer returned                                       |
| Omitting `page` returned the whole collection | Omitting `page` returns the first page only. **Follow `Octo-Next-Page` or you will only read the first 100 records** |

## Errors

Pagination errors return `400 Bad Request` with `error: "BAD_REQUEST"`, an `errorCode` and a descriptive `errorMessage`. The `errorCode` is also returned in the `Ventrata-Error-Code` response header.

| `errorCode`                  | Cause                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `CURSOR_PAGINATION_REQUIRED` | A numeric `page` was sent. Start without `page` and follow `Octo-Next-Page`. |
| `PER_PAGE_RENAMED`           | The obsolete `perPage` parameter was sent. Use `limit`.                      |
| `INVALID_LIMIT`              | `limit` is not a whole number from `1` to `100`.                             |

A malformed or altered cursor returns `BAD_REQUEST`.

```json
{
  "error": "BAD_REQUEST",
  "errorCode": "CURSOR_PAGINATION_REQUIRED",
  "errorMessage": "…"
}
```

## Questions

For help with pagination or anything else in your integration, contact <connectivity@ventrata.com>.
