> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Learn how Tilta's offset-based pagination works, how to iterate through pages, and how to detect when you have reached the last page.

All Tilta list endpoints use **offset-based pagination**, which lets you retrieve large result sets in manageable chunks by specifying a starting position and a maximum page size. Every paginated response includes a `total` field that tells you how many records exist in total, so you always know when you have retrieved everything.

## Query parameters

Pass the following query parameters on any list endpoint to control pagination:

| Parameter | Type    | Default | Description                                                                                                                                                    |
| --------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`  | Integer | `0`     | The zero-based index of the first item to return. An offset of `0` returns items starting from the very beginning of the result set.                           |
| `limit`   | Integer | `100`   | The maximum number of items to return in a single response. `100` is also the highest accepted value – a larger `limit` is rejected with a `400`, not clamped. |

## How to paginate

<Steps>
  <Step title="Request the first page">
    Start with `offset=0` and your desired `limit`. The response body will include the first batch of results and a `total` field indicating how many records exist across all pages.

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.tilta.io/v1/orders?limit=100&offset=0' \
         --header 'Authorization: Bearer YOUR_API_KEY' \
         --header 'accept: application/json'
    ```
  </Step>

  <Step title="Inspect the response">
    The response contains the result array and pagination metadata:

    ```json theme={null}
    {
      "items": [ /* up to 100 order objects */ ],
      "total": 347,
      "limit": 100,
      "offset": 0
    }
    ```

    In this example, `total` is `347`, meaning there are three more pages to fetch after this one.
  </Step>

  <Step title="Request the next page">
    Calculate the next offset by adding the previous `limit` to the previous `offset`:

    ```
    next_offset = previous_offset + previous_limit
    ```

    For the second page:

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.tilta.io/v1/orders?limit=100&offset=100' \
         --header 'Authorization: Bearer YOUR_API_KEY' \
         --header 'accept: application/json'
    ```
  </Step>

  <Step title="Detect the last page">
    You have retrieved all records when the **next offset would exceed the total**:

    ```
    if (next_offset >= total) → stop
    ```

    For the example above with `total=347` and `limit=100`:

    | Page | Offset | Items returned   |
    | ---- | ------ | ---------------- |
    | 1    | 0      | 100              |
    | 2    | 100    | 100              |
    | 3    | 200    | 100              |
    | 4    | 300    | 47               |
    | –    | 400    | Stop – 400 ≥ 347 |
  </Step>
</Steps>

## Complete pagination loop

The example below shows a full pagination loop in Python that collects every order into a single list:

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.tilta.io/v1/orders"
LIMIT = 100

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json",
}

all_orders = []
offset = 0

while True:
    response = requests.get(
        BASE_URL,
        headers=headers,
        params={"limit": LIMIT, "offset": offset},
    )
    response.raise_for_status()
    data = response.json()

    all_orders.extend(data["items"])

    offset += LIMIT
    if offset >= data["total"]:
        break

print(f"Fetched {len(all_orders)} orders in total.")
```

<Tip>
  Request the largest `limit` your use case allows to minimise the number of round trips. For bulk exports or background sync jobs, a `limit` of `100` is a good starting point. For real-time UI pagination, a smaller `limit` (e.g. `20`) typically provides a better user experience.
</Tip>

<Note>
  Offset-based pagination reflects the state of the result set **at query time**. If records are created or deleted between page requests, you may see slight inconsistencies (a record appearing on two pages, or being skipped). For critical reconciliation tasks, compare against the `total` field and re-fetch if the count changes unexpectedly.
</Note>