Get one event
/events/{id}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 | required | Bearer <key>. A btk_live_… or btk_test_… key. |
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | required | 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. | 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.
idintegerrequiredEvent id.
namestring | nullartiststring | nullHeadliner or display title.
datestring | nullEvent date, typically
YYYY-MM-DD.absolute_timestring | nullEvent start time as entered (typically ISO 8601).
doors_timestring | nullconcert_skustring | nullThe event's reference code.
venue_idinteger | nullvenue_stringstring | nullVenue name as text.
venueVenue | nullChild attributes
idintegernamestring | nulladdressstring | nullcitystring | nullstatestring | nullzip_codestring | nulltimezonestring | nullIANA time zone name, e.g.
America/Chicago, when set.
event_image_urlstring | nullis_sold_outbooleanTrue when the event is marked sold out or every active ticket type is sold out.
low_ticket_warningbooleanTrue when any active ticket type is low.
locationsarray of EventTicketTypeEvery ticket type of the event, including ones switched off (
is_active: false) and ones not sold on their own, sorted by name. Sell fromGET /events/{id}/locations, not from this list.Child attributes
idintegerrequiredTicket type (location) id.
event_idintegernamestring | nulldescriptionstring | nullpriceintegerPrice per ticket, in cents.
available_quantityintegerTickets left;
-1= unlimited.is_sold_outbooleanlow_ticket_warningbooleanTrue when only a few tickets are left.
is_activeboolean | nullFalse for a ticket type that is switched off.
Example: event
{
"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
Example: invalid_event_id
{
"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
Example: missing_api_key
{
"error": "missing_api_key",
"message": "Authorization: Bearer btk_… required"
}Example: invalid_api_key
{
"error": "invalid_api_key"
}403 The key lacks the required scope, or API access is off for the account.
Schema: Error
Example: insufficient_scope
{
"error": "insufficient_scope",
"required": "events:read"
}Example: partner_api_disabled
{
"error": "partner_api_disabled"
}404 No such event on your account, a test event, or an event whose sales have closed.
Schema: Error
Example: event_not_found
{
"error": "event_not_found"
}405 The HTTP method is not supported on this path.
Schema: Error
Example: method_not_allowed
{
"error": "method_not_allowed"
}409 The concert_sku matches more than one event on your account. Use the numeric id.
Schema: Error
Example: ambiguous_concert_sku
{
"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.
Headers
| Name | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before retrying (at least 1). |
Schema: Error
Example: partner_rate_limited
{
"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
Example: upstream_error
{
"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
| Name | Type | Description |
|---|---|---|
Retry-After | integer | Seconds to wait before retrying. |
Schema: Error
Example: auth_unavailable
{
"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
{
"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 "https://app.bettertickets.com/api/partner/v1/events/1001" \
-H "Authorization: Bearer $BETTERTICKETS_API_KEY"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();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
$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);