# Pagination

`GET /events` is the only paginated operation. Other operations return their full result in one response.

## Parameters

| Parameter | Default | Notes |
|---|---|---|
| `page` | `1` | Page number, starting at 1. |
| `per_page` | `20` | Events per page. Use 100 or fewer; larger values may be limited in future. |

Both must be whole numbers of 1 or more, written as plain digits (`2`, not `2.0`, `+2` or `0x2`). Anything else, or the same parameter sent twice, answers `400`:

| Parameter | Error |
|---|---|
| `page` | `400 invalid_page` |
| `per_page` | `400 invalid_per_page` |

An empty value (`?page=`) counts as not sent and uses the default. The `venue_id` filter must be plain digits too, or it answers `400 invalid_venue_id`.

```json
{ "error": "invalid_per_page", "message": "per_page must be a whole number of 1 or more" }
```

Fix the value instead of retrying.

## Response

```json
{
  "itemsReceived": 20,
  "curPage": 1,
  "nextPage": 2,
  "prevPage": null,
  "itemsTotal": 57,
  "pageTotal": 3,
  "items": [ … ]
}
```

| Field | Meaning |
|---|---|
| `items` | The events on this page. |
| `itemsReceived` | Number of events on this page. |
| `curPage` | This page number. |
| `nextPage` | The next page number, or `null` on the last page. |
| `prevPage` | The previous page number, or `null` on the first page. |
| `itemsTotal` | Events matching your filters across all pages. |
| `pageTotal` | Number of pages. |

## Reading every page

Follow `nextPage` until it is `null`:

```js
const BASE = 'https://app.bettertickets.com/api/partner/v1';
const headers = { Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}` };

async function allEvents(filters = {}) {
  const events = [];
  let page = 1;
  while (page) {
    const qs = new URLSearchParams({ ...filters, page: String(page), per_page: '100' });
    const res = await fetch(`${BASE}/events?${qs}`, { headers });
    if (!res.ok) throw new Error(`GET /events failed: ${res.status}`);
    const body = await res.json();
    events.push(...body.items);
    page = body.nextPage;
  }
  return events;
}
```

```python
import os, requests

BASE = "https://app.bettertickets.com/api/partner/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"}

def all_events(**filters):
    events, page = [], 1
    while page:
        r = requests.get(f"{BASE}/events", headers=HEADERS,
                         params={**filters, "page": page, "per_page": 100}, timeout=30)
        r.raise_for_status()
        body = r.json()
        events.extend(body["items"])
        page = body["nextPage"]
    return events
```

Events are sorted by date, earliest first. Results can shift between pages if events change while you page, so treat a full sync as a snapshot and de-duplicate by `id`.
