Get live availability of a ticket type
/locations/{id}/availabilityTickets left for one ticket type. Read-only: nothing is reserved.
#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 | integer | required | Ticket type (location) id, plain digits only. (min 1) Example: 2001 |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
requested_quantity | integer | optional | Quantity to test can_fulfill against. Send a whole number as plain digits. Defaults to 1; a value that cannot be read as a positive whole number is ignored and the default applies. Other numeric forms, such as 2.0 or 1e1, may be read as numbers. (min 1, default 1) Example: 2 |
#Responses
| Status | Meaning | Error codes |
|---|---|---|
| 200 | Availability. | — |
| 400 | The id is not plain digits of 1 or more (for example 5.0 or 1e1). | invalid_location_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 ticket type on your account, a ticket type that is not sold on its own, one of a test event, or one whose event's sales have closed. | location_not_found |
| 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 Availability.
Schema: Availability
Live availability of one ticket type. -1 in a quantity field means unlimited. 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.
location_idintegerrequiredevent_idinteger | nullrequiredeffective_availableinteger | nullrequiredTickets left after tickets sold and checkouts in progress.
-1= unlimited. Use this to show "tickets left".available_quantityinteger | nullrequiredTickets left after tickets sold only.
-1= unlimited.can_fulfillboolean | nullrequiredFalse when
available_quantityis belowrequested_quantity, or the ticket type is not for sale. It does not count checkouts in progress; compareeffective_availablewith your quantity for the stricter answer.
Example: limited
{
"location_id": 2001,
"event_id": 1001,
"effective_available": 1184,
"available_quantity": 1188,
"can_fulfill": true
}Example: unlimited
{
"location_id": 2002,
"event_id": 1001,
"effective_available": -1,
"available_quantity": -1,
"can_fulfill": true
}400 The id is not plain digits of 1 or more (for example 5.0 or 1e1).
Schema: Error
Example: invalid_location_id
{
"error": "invalid_location_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 ticket type on your account, a ticket type that is not sold on its own, one of a test event, or one whose event's sales have closed.
Schema: Error
Example: location_not_found
{
"error": "location_not_found"
}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/locations/2001/availability?requested_quantity=2" \
-H "Authorization: Bearer $BETTERTICKETS_API_KEY"async function main() {
const res = await fetch('https://app.bettertickets.com/api/partner/v1/locations/2001/availability?requested_quantity=2', {
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/locations/2001/availability",
headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"},
params={"requested_quantity": 2},
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/locations/2001/availability?requested_quantity=2');
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);