Look up one list row by key
/lists/{id}/rowsFinds the row whose key column equals key. Returns only the columns the list exposes to the API. Test keys read the list's Staging rows, live keys Production rows.
404 row_not_found also when the row was removed or is inactive, and for Production reads while the list's Production switch is off.
Key cleaning. key is cleaned the same way imported keys are, by the key column's type:
| Key column type | Cleaning |
|---|---|
| Any | Trimmed and lower-cased |
| Must be a valid email address | |
| Phone | Spaces, parentheses, dots and dashes removed; 7–15 digits with an optional leading + must remain ((555) 010-1234 finds 5550101234) |
| Date | 2027-01-21, 1/21/2027 or Jan 21, 2027 |
A missing or blank key, or one over 2,000 characters, gets 400 invalid_key "Pass ?key=…". A key that does not fit the column type, or is over 255 characters after cleaning, gets 400 invalid_key "The key does not match the type of the list key column."
#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 | Custom List id (shown in the list's settings). Send plain digits. Other numeric forms, such as 1e1 or 0x10, may be read as a different list id, so build the path only from the id as shown. (min 1) Example: 4001 |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
key | string | required | Value of the list's key column. URL-encode it (for example with encodeURIComponent, URLSearchParams or requests params), so + and @ arrive intact. Cleaned before matching (see the operation description). (min length 1, max length 2000) Example: fan@example.com |
#Responses
| Status | Meaning | Error codes |
|---|---|---|
| 200 | The row. | — |
| 400 | Bad list id or key. | invalid_list_id invalid_key |
| 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, API access or Custom Lists is off for the account, or API Access is off for this list. | insufficient_scope partner_api_disabled partner_lists_disabled list_api_disabled |
| 404 | No such list on your account (or it is archived), or no active row with that key. | list_not_found row_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 | upstream_error: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. request_refused: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. request_refused can also arrive with a 4xx status; branch on error, not only on the status. | upstream_error request_refused |
| 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. On Custom Lists calls, FEATURE_GATE_UNAVAILABLE can also arrive as a bare { "error": "FEATURE_GATE_UNAVAILABLE" } with no Retry-After, retryable or retry_after_seconds; wait 5 seconds before retrying. | auth_unavailable FEATURE_GATE_UNAVAILABLE |
200 The row.
Schema: ListRowLookupResponse
list_idintegerrequiredrowobjectrequiredChild attributes
row_keystringrequiredThe cleaned key (trimmed, lower-cased).
added_atinteger (int64)requiredWhen the row first arrived, epoch milliseconds. Never reset by later writes.
updated_atinteger (int64)requiredLast change, epoch milliseconds.
dataobjectrequiredOnly the columns the list exposes to the API (chosen in the list's settings).
Example: row
{
"list_id": 4001,
"row": {
"row_key": "fan@example.com",
"added_at": 1795456800000,
"updated_at": 1795460400000,
"data": {
"email": "fan@example.com",
"tier": "VIP"
}
}
}400 Bad list id or key.
Schema: Error
Example: invalid_list_id
{
"error": "invalid_list_id"
}Example: missing_key — No key, a blank key, or a key over 2,000 characters.
{
"error": "invalid_key",
"message": "Pass ?key=<value of the list key column>."
}Example: invalid_key — The key does not fit the key column type, or is over 255 characters after cleaning.
{
"error": "invalid_key",
"message": "The key does not match the type of the list key column."
}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, API access or Custom Lists is off for the account, or API Access is off for this list.
Schema: Error
Example: insufficient_scope
{
"error": "insufficient_scope",
"required": "lists:read"
}Example: partner_api_disabled
{
"error": "partner_api_disabled"
}Example: partner_lists_disabled
{
"error": "partner_lists_disabled",
"message": "Custom Lists is not enabled for this account."
}Example: list_api_disabled
{
"error": "list_api_disabled",
"message": "API access is turned off for this list. Turn it on in the list settings."
}404 No such list on your account (or it is archived), or no active row with that key.
Schema: Error
Example: list_not_found
{
"error": "list_not_found"
}Example: row_not_found
{
"error": "row_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 upstream_error: BetterTickets could not complete the call; retry with backoff and a small cap on attempts. request_refused: the call was refused for an unlisted reason; do not retry the same request, and contact BetterTickets if it persists. request_refused can also arrive with a 4xx status; branch on error, not only on the status.
Schema: Error
Example: upstream_error
{
"error": "upstream_error"
}Example: request_refused
{
"error": "request_refused"
}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. On Custom Lists calls, FEATURE_GATE_UNAVAILABLE can also arrive as a bare { "error": "FEATURE_GATE_UNAVAILABLE" } with no Retry-After, retryable or retry_after_seconds; wait 5 seconds before retrying.
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
}Example: FEATURE_GATE_UNAVAILABLE_bare
{
"error": "FEATURE_GATE_UNAVAILABLE"
}#Code samples
Set BETTERTICKETS_API_KEY on your server. Never send a key from a browser.
curl "https://app.bettertickets.com/api/partner/v1/lists/4001/rows?key=fan%40example.com" \
-H "Authorization: Bearer $BETTERTICKETS_API_KEY"async function main() {
const res = await fetch('https://app.bettertickets.com/api/partner/v1/lists/4001/rows?key=fan%40example.com', {
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/lists/4001/rows",
headers={"Authorization": f"Bearer {os.environ['BETTERTICKETS_API_KEY']}"},
params={"key": "fan@example.com"},
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/lists/4001/rows?key=fan%40example.com');
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);