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

# Pagination

> Cursor-based pagination in the V2 Vendor API

<Note>
  **V2 Preview** — This pagination model is part of the V2 API preview. Breaking changes may occur.
</Note>

## Overview

The V2 API uses **cursor-based pagination** (Relay-style) instead of offset-based pagination. Cursors provide stable, consistent results even when data is being added or removed between requests.

## Pagination Parameters

| Parameter | Type            | Description                                     |
| --------- | --------------- | ----------------------------------------------- |
| `first`   | integer (1–100) | Number of items to return (forward pagination)  |
| `after`   | string          | Cursor to start after (forward pagination)      |
| `last`    | integer (1–100) | Number of items to return (backward pagination) |
| `before`  | string          | Cursor to start before (backward pagination)    |

Default page size is **20** items. Maximum is **100**.

<Warning>
  You cannot combine `first` with `last`, or `after` with `before`, in the same request.
</Warning>

## Response Format

All paginated endpoints return a `pageInfo` object alongside the data:

```json theme={null}
{
  "success": true,
  "data": {
    "items": [ ... ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjY1YTFiMmMzZDRlNWY2... ",
      "endCursor": "eyJpZCI6IjY1YTFiMmMzZDRlNWY3..."
    },
    "totalCount": 150
  }
}
```

| Field             | Type           | Description                                     |
| ----------------- | -------------- | ----------------------------------------------- |
| `hasNextPage`     | boolean        | Whether more items exist after this page        |
| `hasPreviousPage` | boolean        | Whether more items exist before this page       |
| `startCursor`     | string \| null | Cursor of the first item in this page           |
| `endCursor`       | string \| null | Cursor of the last item in this page            |
| `totalCount`      | integer        | Total number of matching items (when available) |

## Forward Pagination

Fetch the first page, then use `endCursor` to get the next:

```bash theme={null}
# First page of your orders
curl "https://production-api.puppetvendors.com/orders?first=10" \
  -H "x-access-token: YOUR_VENDOR_TOKEN"

# Next page (use endCursor from previous response)
curl "https://production-api.puppetvendors.com/orders?first=10&after=eyJpZCI6IjY1YTF..." \
  -H "x-access-token: YOUR_VENDOR_TOKEN"
```

## Backward Pagination

Use `last` and `before` to paginate backwards:

```bash theme={null}
# Last 10 items before a cursor
curl "https://production-api.puppetvendors.com/orders?last=10&before=eyJpZCI6IjY1YTF..." \
  -H "x-access-token: YOUR_VENDOR_TOKEN"
```

## Full Iteration Example

```javascript theme={null}
const BASE_URL = 'https://production-api.puppetvendors.com';

let hasMore = true;
let cursor = null;

while (hasMore) {
  const params = cursor
    ? `first=50&after=${cursor}`
    : 'first=50';

  const response = await fetch(`${BASE_URL}/orders?${params}`, {
    headers: { 'x-access-token': VENDOR_TOKEN }
  });

  const { data } = await response.json();

  // Process your orders
  for (const order of data.items) {
    console.log(order.orderName);
  }

  hasMore = data.pageInfo.hasNextPage;
  cursor = data.pageInfo.endCursor;
}
```

## Python Example

```python theme={null}
import requests

BASE_URL = "https://production-api.puppetvendors.com"
headers = {"x-access-token": VENDOR_TOKEN}

cursor = None
while True:
    params = {"first": 50}
    if cursor:
        params["after"] = cursor

    resp = requests.get(f"{BASE_URL}/orders", headers=headers, params=params)
    data = resp.json()["data"]

    for order in data["items"]:
        print(order["orderName"])

    if not data["pageInfo"]["hasNextPage"]:
        break
    cursor = data["pageInfo"]["endCursor"]
```