List events
/eventsLists 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 | required | Bearer <key>. A btk_live_… or btk_test_… key. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | integer | optional | 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 | optional | 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 | optional | Only events at this venue. Plain digits; anything else answers 400 invalid_venue_id. (min 0) Example: 3001 |
from_date | string (date) | optional | Only events on or after this date (YYYY-MM-DD). Example: 2027-07-01 |
to_date | string (date) | optional | Only events on or before this date (YYYY-MM-DD, whole day included). Example: 2027-07-31 |
search | string | optional | 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. | 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.
itemsarray of EventSummaryrequiredChild attributes
idintegerrequiredEvent id.
namestring | nullartiststring | nullHeadliner or display title. Either
nameorartistis always set.datestring | nullEvent date, typically
YYYY-MM-DD.absolute_timestring | nullEvent start time as entered (typically ISO 8601). Always set on listed events.
doors_timestring | nullconcert_skustring | nullThe event's reference code. Accepted in place of
idbyGET /events/{id}.venue_idinteger | nullVenue id; use it with the
venue_idfilter.venue_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_outbooleanThe event is marked sold out.
location_countintegerNumber of active ticket types.
locationsarray of EventSummaryTicketTypeChild attributes
idintegerrequiredTicket type (location) id.
event_idintegernamestring | null
itemsReceivedintegerEvents on this page.
curPageintegernextPageinteger | nullprevPageinteger | nullitemsTotalintegerpageTotalinteger
Example: page
{
"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
Example: invalid_page
{
"error": "invalid_page",
"message": "page must be a whole number of 1 or more"
}Example: invalid_per_page
{
"error": "invalid_per_page",
"message": "per_page must be a whole number of 1 or more"
}Example: invalid_venue_id
{
"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
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"
}405 The HTTP method is not supported on this path.
Schema: Error
Example: method_not_allowed
{
"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.
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?from_date=2027-07-01&to_date=2027-07-31" \
-H "Authorization: Bearer $BETTERTICKETS_API_KEY"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();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
$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);