# List events

`GET /events`

- **Full URL:** `https://app.bettertickets.com/api/partner/v1/events`
- **Scope required:** `events:read`
- **Auth:** `Authorization: Bearer <btk_live_… or btk_test_… key>`

Lists your account's events that are active, on sale, not test events, and have a title and start time, sorted by date (earliest first).

`from_date` / `to_date` filter on the event date only. An event can stay listed for up to about an hour after its sales close, while `GET /events/{id}` already answers `404`; check the detail before selling.

## Request

### Headers

| Name | Type | Required | Description |
|---|---|---|---|
| `Authorization` | string | Yes | Bearer <key>. A `btk_live_…` or `btk_test_…` key. |

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number: a whole number of 1 or more, as plain digits. Anything else answers `400 invalid_page`. An empty value uses the default. (min 1, default 1) Example: `1` |
| `per_page` | integer | No | Events per page: a whole number of 1 or more, as plain digits. Anything else answers `400 invalid_per_page`. Use 100 or fewer; larger values may be limited in future. An empty value uses the default. (min 1, default 20) Example: `20` |
| `venue_id` | integer | No | Only events at this venue. Plain digits; anything else answers `400 invalid_venue_id`. (min 0) Example: `3001` |
| `from_date` | string (date) | No | Only events on or after this date (`YYYY-MM-DD`). Example: `2027-07-01` |
| `to_date` | string (date) | No | Only events on or before this date (`YYYY-MM-DD`, whole day included). Example: `2027-07-31` |
| `search` | string | No | Text contained in the event name, artist or venue name. Example: `festival` |

## Responses

| Status | Meaning | Error codes |
|---|---|---|
| 200 | A page of events. | — |
| 400 | `page`, `per_page` or `venue_id` is not plain digits, is below its minimum, or is sent more than once. Fix the value instead of retrying. | `invalid_page`, `invalid_per_page`, `invalid_venue_id` |
| 401 | No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same `invalid_api_key` is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers `503 auth_unavailable` instead. Repeated requests with a missing or invalid key from one IP address are answered `429 partner_rate_limited` instead of `401`. | `missing_api_key`, `invalid_api_key` |
| 403 | The key lacks the required scope, or API access is off for the account. | `insufficient_scope`, `partner_api_disabled` |
| 405 | The HTTP method is not supported on this path. | `method_not_allowed` |
| 429 | Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered `429` instead of `401`). Wait `Retry-After` seconds. See [Rate Limits](https://docs.bettertickets.com/rate-limits). | `partner_rate_limited` |
| 502 | BetterTickets could not load the data. Retry later. | `upstream_error` |
| 503 | BetterTickets could not check the key (`auth_unavailable`) or confirm the account's settings (`FEATURE_GATE_UNAVAILABLE`) for a moment. Safe to retry after `Retry-After` seconds; if the header is missing, wait 5 seconds. Retrying `auth_unavailable` faster than `Retry-After` gets `429 partner_rate_limited`. | `auth_unavailable`, `FEATURE_GATE_UNAVAILABLE` |

### 200

A page of events.

Schema `EventPage`:

One page of events. Only the fields below are documented. Responses can contain other fields; they are not part of the API, may change or disappear without notice, and must not be relied on.

- `items` (array of EventSummary, required)
  - `id` (integer, required) — Event id.
  - `name` (string | null)
  - `artist` (string | null) — Headliner or display title. Either `name` or `artist` is always set.
  - `date` (string | null) — Event date, typically `YYYY-MM-DD`.
  - `absolute_time` (string | null) — Event start time as entered (typically ISO 8601). Always set on listed events.
  - `doors_time` (string | null)
  - `concert_sku` (string | null) — The event's reference code. Accepted in place of `id` by `GET /events/{id}`.
  - `venue_id` (integer | null) — Venue id; use it with the `venue_id` filter.
  - `venue_string` (string | null) — Venue name as text.
  - `venue` (Venue | null)
    - `id` (integer)
    - `name` (string | null)
    - `address` (string | null)
    - `city` (string | null)
    - `state` (string | null)
    - `zip_code` (string | null)
    - `timezone` (string | null) — IANA time zone name, e.g. `America/Chicago`, when set.
  - `event_image_url` (string | null)
  - `is_sold_out` (boolean) — The event is marked sold out.
  - `location_count` (integer) — Number of active ticket types.
  - `locations` (array of EventSummaryTicketType)
    - `id` (integer, required) — Ticket type (location) id.
    - `event_id` (integer)
    - `name` (string | null)
- `itemsReceived` (integer) — Events on this page.
- `curPage` (integer)
- `nextPage` (integer | null)
- `prevPage` (integer | null)
- `itemsTotal` (integer)
- `pageTotal` (integer)

Example `page`:

```json
{
  "itemsReceived": 1,
  "curPage": 1,
  "nextPage": null,
  "prevPage": null,
  "itemsTotal": 1,
  "pageTotal": 1,
  "items": [
    {
      "id": 1001,
      "name": "Summer Roots Festival 2027",
      "artist": "Summer Roots Festival 2027",
      "date": "2027-07-16",
      "absolute_time": "2027-07-16T16:00:00-05:00",
      "doors_time": "3:00 PM",
      "concert_sku": "SRF_07-16-2027",
      "venue_id": 3001,
      "venue_string": "Riverside Park Bandshell",
      "venue": {
        "id": 3001,
        "name": "Riverside Park Bandshell",
        "address": "100 Example Ave",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62701",
        "timezone": "America/Chicago"
      },
      "event_image_url": "https://example.com/images/summer-roots.jpg",
      "is_sold_out": false,
      "location_count": 2,
      "locations": [
        {
          "id": 2001,
          "event_id": 1001,
          "name": "GA Weekend"
        },
        {
          "id": 2002,
          "event_id": 1001,
          "name": "VIP Weekend"
        }
      ]
    }
  ]
}
```

### 400

`page`, `per_page` or `venue_id` is not plain digits, is below its minimum, or is sent more than once. Fix the value instead of retrying.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `invalid_page`:

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

Example `invalid_per_page`:

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

Example `invalid_venue_id`:

```json
{
  "error": "invalid_venue_id",
  "message": "venue_id must be a whole number"
}
```

### 401

No key, or the key was checked and is unknown, revoked, expired or has the wrong prefix. The same `invalid_api_key` is returned for every kind of bad key. Do not retry it. A temporary problem checking the key answers `503 auth_unavailable` instead. Repeated requests with a missing or invalid key from one IP address are answered `429 partner_rate_limited` instead of `401`.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `missing_api_key`:

```json
{
  "error": "missing_api_key",
  "message": "Authorization: Bearer btk_… required"
}
```

Example `invalid_api_key`:

```json
{
  "error": "invalid_api_key"
}
```

### 403

The key lacks the required scope, or API access is off for the account.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `insufficient_scope`:

```json
{
  "error": "insufficient_scope",
  "required": "events:read"
}
```

Example `partner_api_disabled`:

```json
{
  "error": "partner_api_disabled"
}
```

### 405

The HTTP method is not supported on this path.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `method_not_allowed`:

```json
{
  "error": "method_not_allowed"
}
```

### 429

Too many requests from this key or from your IP address, or repeated requests with a missing or invalid key from one IP address (answered `429` instead of `401`). Wait `Retry-After` seconds. See [Rate Limits](https://docs.bettertickets.com/rate-limits).

Headers:

- `Retry-After` (integer) — Seconds to wait before retrying (at least 1).

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `partner_rate_limited`:

```json
{
  "error": "partner_rate_limited",
  "message": "Too many Partner API requests. Slow down and retry after Retry-After seconds.",
  "retry_after_seconds": 42
}
```

### 502

BetterTickets could not load the data. Retry later.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `upstream_error`:

```json
{
  "error": "upstream_error"
}
```

### 503

BetterTickets could not check the key (`auth_unavailable`) or confirm the account's settings (`FEATURE_GATE_UNAVAILABLE`) for a moment. Safe to retry after `Retry-After` seconds; if the header is missing, wait 5 seconds. Retrying `auth_unavailable` faster than `Retry-After` gets `429 partner_rate_limited`.

Headers:

- `Retry-After` (integer) — Seconds to wait before retrying.

Schema: `Error` (see [Errors](https://docs.bettertickets.com/errors.md)).

Example `auth_unavailable`:

```json
{
  "error": "auth_unavailable",
  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
  "retryable": true,
  "retry_after_seconds": 5
}
```

Example `FEATURE_GATE_UNAVAILABLE`:

```json
{
  "error": "FEATURE_GATE_UNAVAILABLE",
  "retryable": true,
  "retry_after_seconds": 5
}
```

## Code samples

Set `BETTERTICKETS_API_KEY` on your server. Never send a key from a browser.

### cURL

```bash
curl "https://app.bettertickets.com/api/partner/v1/events?from_date=2027-07-01&to_date=2027-07-31" \
  -H "Authorization: Bearer $BETTERTICKETS_API_KEY"
```

### Node.js

```js
async function main() {
  const res = await fetch('https://app.bettertickets.com/api/partner/v1/events?from_date=2027-07-01&to_date=2027-07-31', {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${process.env.BETTERTICKETS_API_KEY}`,
    },
  });

  // Error pages from a proxy may not be JSON, so parse defensively.
  const text = await res.text();
  let data = {};
  try { data = text ? JSON.parse(text) : {}; } catch { data = {}; }
  if (!res.ok) {
    // Branch on data.error, e.g. "partner_rate_limited"
    throw new Error(`${res.status} ${data.error || 'unknown'}`);
  }
  console.log(data);
}

main();
```

### Python

```python
import os
import requests

res = requests.request(
    "GET",
    "https://app.bettertickets.com/api/partner/v1/events",
    headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"},
    params={"from_date": "2027-07-01", "to_date": "2027-07-31"},
    timeout=30,
)
is_json = res.headers.get("content-type", "").startswith("application/json")
data = res.json() if is_json else {}
if not res.ok:
    # Branch on data["error"], e.g. "partner_rate_limited"
    raise RuntimeError(f"{res.status_code} {data.get('error')}")
print(data)
```

### PHP

```php
<?php
$ch = curl_init('https://app.bettertickets.com/api/partner/v1/events?from_date=2027-07-01&to_date=2027-07-31');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BETTERTICKETS_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode((string) $body, true) ?? [];
if ($status >= 400) {
    // Branch on $data['error'], e.g. "partner_rate_limited"
    throw new RuntimeException($status . ' ' . ($data['error'] ?? 'unknown'));
}
print_r($data);
```
