# Get one event

`GET /events/{id}`

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

One event of your account, by numeric id or `concert_sku`. Answers `404 event_not_found` for events of other accounts, test events, and events whose sales have closed (inactive, off sale, or past their sales cutoff).

`locations` lists **every** ticket type of the event, including ones that are switched off. Sell from `GET /events/{id}/locations` instead.

## Request

### Headers

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

### Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | Yes | Numeric event id, or the event's `concert_sku` (2–80 characters, matched case-insensitively). (min length 1, max length 80) Example: `1001` |

## Responses

| Status | Meaning | Error codes |
|---|---|---|
| 200 | The event. | — |
| 400 | The reference is neither a number nor a valid `concert_sku` (for example it contains `/`). | `invalid_event_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` |
| 404 | No such event on your account, a test event, or an event whose sales have closed. | `event_not_found` |
| 405 | The HTTP method is not supported on this path. | `method_not_allowed` |
| 409 | The `concert_sku` matches more than one event on your account. Use the numeric id. | `ambiguous_concert_sku` |
| 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

The event.

Schema `Event`:

One event, as returned by `GET /events/{id}`. 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.

- `id` (integer, required) — Event id.
- `name` (string | null)
- `artist` (string | null) — Headliner or display title.
- `date` (string | null) — Event date, typically `YYYY-MM-DD`.
- `absolute_time` (string | null) — Event start time as entered (typically ISO 8601).
- `doors_time` (string | null)
- `concert_sku` (string | null) — The event's reference code.
- `venue_id` (integer | null)
- `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) — True when the event is marked sold out or every active ticket type is sold out.
- `low_ticket_warning` (boolean) — True when any active ticket type is low.
- `locations` (array of EventTicketType) — **Every** ticket type of the event, including ones switched off (`is_active: false`) and ones not sold on their own, sorted by name. Sell from `GET /events/{id}/locations`, not from this list.
  - `id` (integer, required) — Ticket type (location) id.
  - `event_id` (integer)
  - `name` (string | null)
  - `description` (string | null)
  - `price` (integer) — Price per ticket, in **cents**.
  - `available_quantity` (integer) — Tickets left; `-1` = unlimited.
  - `is_sold_out` (boolean)
  - `low_ticket_warning` (boolean) — True when only a few tickets are left.
  - `is_active` (boolean | null) — False for a ticket type that is switched off.

Example `event`:

```json
{
  "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,
  "low_ticket_warning": false,
  "locations": [
    {
      "id": 2001,
      "event_id": 1001,
      "name": "GA Weekend",
      "description": "General admission, both days.",
      "price": 5000,
      "available_quantity": 1188,
      "is_sold_out": false,
      "low_ticket_warning": false,
      "is_active": true
    }
  ]
}
```

### 400

The reference is neither a number nor a valid `concert_sku` (for example it contains `/`).

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

Example `invalid_event_id`:

```json
{
  "error": "invalid_event_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`.

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"
}
```

### 404

No such event on your account, a test event, or an event whose sales have closed.

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

Example `event_not_found`:

```json
{
  "error": "event_not_found"
}
```

### 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"
}
```

### 409

The `concert_sku` matches more than one event on your account. Use the numeric id.

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

Example `ambiguous_concert_sku`:

```json
{
  "error": "ambiguous_concert_sku"
}
```

### 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/1001" \
  -H "Authorization: Bearer $BETTERTICKETS_API_KEY"
```

### Node.js

```js
async function main() {
  const res = await fetch('https://app.bettertickets.com/api/partner/v1/events/1001', {
    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/1001",
    headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"},
    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/1001');
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);
```
