# Pagination

All list endpoints in the Tote Online Ordering API use **cursor-based pagination**. Cursors are opaque strings that point to a position in the result set. This approach provides stable pagination even when the underlying data changes between requests.

## Request Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `cursor` | string | No | Opaque cursor for the next page. Obtained from the `next_cursor` field of a previous response. Omit for the first page. |
| `limit` | integer | No | Maximum number of results per page. Default and maximum values depend on the endpoint (see [Limit Tiers](#limit-tiers) below). |


## Response Format

Every paginated response wraps results in a `data` array and includes a `pagination` object:


```json
{
  "data": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "QuickStop #247" },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "QuickStop #312" }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6ImIyYzNkNGU1LWY2YTctODkwMS1iY2RlLWYxMjM0NTY3ODkwMSJ9"
  }
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `data` | array | The results for the current page. |
| `pagination.has_more` | boolean | `true` if more results exist beyond this page. |
| `pagination.next_cursor` | string or null | Opaque cursor for the next page. Pass as the `cursor` query parameter. `null` when there are no more results. |


When `has_more` is `false` and `next_cursor` is `null`, you have reached the last page.

## Limit Tiers

Different endpoints support different page sizes based on typical payload size and usage patterns:

| Endpoints | Default `limit` | Maximum `limit` |
|  --- | --- | --- |
| `GET /locations`, `GET /orders`, `GET /webhooks` | 20 | 100 |
| `GET /locations/{id}/inventory` | 100 | 500 |


The inventory endpoint supports larger page sizes because inventory queries typically need to check stock levels across many items in a single request. Use `limit=500` when performing bulk stock queries to minimize round trips.

## Paginated Endpoints

The following endpoints support pagination:

| Endpoint | Description |
|  --- | --- |
| `GET /locations` | List locations accessible to your credentials. |
| `GET /orders` | List orders across all locations in your scope. |
| `GET /webhooks` | List webhook subscriptions. |
| `GET /locations/{id}/inventory` | List inventory stock levels for a location. |


## Example: Iterating All Pages

This example fetches all locations by following the `next_cursor` until `has_more` is `false`:


```python
import requests

BASE_URL = "https://sandbox.api.tote.ai/v1/online-ordering"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}


def fetch_all_locations():
    """Iterate through all pages of the locations endpoint."""
    all_locations = []
    cursor = None

    while True:
        params = {"limit": 50}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            f"{BASE_URL}/locations",
            headers=headers,
            params=params,
        )
        response.raise_for_status()
        body = response.json()

        all_locations.extend(body["data"])

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

        cursor = body["pagination"]["next_cursor"]

    return all_locations


locations = fetch_all_locations()
print(f"Fetched {len(locations)} locations")
```

**Key points:**

- Omit the `cursor` parameter on the first request to start from the beginning.
- Cursors are opaque -- do not parse, modify, or construct them. Always use the value returned by the API.
- Cursors are short-lived. If you need to restart pagination from the beginning, omit the `cursor` parameter.
- Results within a page are ordered consistently, but the ordering may vary by endpoint (typically by creation time).


## See Also

- [Getting Started Guide](/online-ordering/guides/01-getting-started#pagination) -- Pagination overview with curl examples.
- [Pagination schema](/assets/pagination.fdbff3a10295b72c0b8a341d4654b2570db91dc1a8565b229a36262e917d9e3e.8e9e6065.yaml) -- OpenAPI schema definition.