BetterTicketsAPI Docs

Events

List events

GET/events
Scope
events:read
Base URL
https://app.bettertickets.com/api/partner/v1
Auth
Bearer API 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

NameTypeRequiredDescription
AuthorizationstringrequiredBearer <key>. A btk_live_… or btk_test_… key.

Query parameters

NameTypeRequiredDescription
pageintegeroptionalPage 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_pageintegeroptionalEvents 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_idintegeroptionalOnly events at this venue. Plain digits; anything else answers 400 invalid_venue_id. (min 0) Example: 3001
from_datestring (date)optionalOnly events on or after this date (YYYY-MM-DD). Example: 2027-07-01
to_datestring (date)optionalOnly events on or before this date (YYYY-MM-DD, whole day included). Example: 2027-07-31
searchstringoptionalText contained in the event name, artist or venue name. Example: festival

#Responses

StatusMeaningError codes
200A page of events.—
400page, 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
401No 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
403The key lacks the required scope, or API access is off for the account.insufficient_scope partner_api_disabled
405The HTTP method is not supported on this path.method_not_allowed
429Too 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
502BetterTickets could not load the data. Retry later.upstream_error
503BetterTickets 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 EventSummaryrequired
    Child attributes
    • idintegerrequired

      Event id.

    • namestring | null
    • artiststring | null

      Headliner or display title. Either name or artist is always set.

    • datestring | null

      Event date, typically YYYY-MM-DD.

    • absolute_timestring | null

      Event start time as entered (typically ISO 8601). Always set on listed events.

    • doors_timestring | null
    • concert_skustring | null

      The event's reference code. Accepted in place of id by GET /events/{id}.

    • venue_idinteger | null

      Venue id; use it with the venue_id filter.

    • venue_stringstring | null

      Venue name as text.

    • venueVenue | null
      Child attributes
      • idinteger
      • namestring | null
      • addressstring | null
      • citystring | null
      • statestring | null
      • zip_codestring | null
      • timezonestring | null

        IANA time zone name, e.g. America/Chicago, when set.

    • event_image_urlstring | null
    • is_sold_outboolean

      The event is marked sold out.

    • location_countinteger

      Number of active ticket types.

    • locationsarray of EventSummaryTicketType
      Child attributes
      • idintegerrequired

        Ticket type (location) id.

      • event_idinteger
      • namestring | null
  • itemsReceivedinteger

    Events on this page.

  • curPageinteger
  • nextPageinteger | null
  • prevPageinteger | null
  • itemsTotalinteger
  • pageTotalinteger

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

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

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

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

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.

Headers

NameTypeDescription
Retry-AfterintegerSeconds to wait before retrying (at least 1).

Schema: Error

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

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

NameTypeDescription
Retry-AfterintegerSeconds to wait before retrying.

Schema: Error

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