Skip to content
Docs

SQL API health

Says whether the API is up and which catalog it serves.

GET https://api.transitlab.nyc/v1/health No key

Needs no key and does not start the query engine, which sleeps after 3 minutes idle; the first query after a quiet spell takes a few seconds longer. Also shows how much of the month’s shared engine time is left.

curl https://api.transitlab.nyc/v1/health
import requests
r = requests.get(
"https://api.transitlab.nyc/v1/health",
timeout=60,
)
r.raise_for_status()
print(r.json())
const res = await fetch("https://api.transitlab.nyc/v1/health")
if (!res.ok) throw new Error(`HTTP ${res.status}`)
console.log(await res.json())

No key needed.

Up.

  • ok boolean required

    True when the API is up and can read the catalog.

  • service string

    Always sql-api.

  • catalog_updated string

    When the catalog the API serves was built.

  • tables integer

    Number of tables.

  • engine_budget object

    The free service’s shared engine time for this calendar month (UTC). Left out if it can’t be read. When none is left, SQL answers 503 until resets_at; tables and health keep working.

  • engine_budget.month string

    The month, like 2026-10.

  • engine_budget.hours_total number

    Engine hours for the month.

  • engine_budget.hours_remaining number

    Engine hours left, to a tenth.

  • engine_budget.available boolean

    False once the hours are spent.

  • engine_budget.resets_at string

    When the next month starts, ISO 8601 UTC.

  • time string

    Server time, ISO 8601 UTC.

Example
{
"ok": true,
"service": "sql-api",
"catalog_updated": "2026-10-06T11:38:53Z",
"tables": 15,
"engine_budget": {
"month": "2026-10",
"hours_total": 150,
"hours_remaining": 149.8,
"available": true,
"resets_at": "2026-11-01T00:00:00.000Z"
},
"time": "2026-10-06T16:06:26.871Z"
}
StatusWhen
503Unavailable. The catalog could not be read.

Error responses carry this body:

  • error string required

    A short code: unauthorized, rate_limited, daily_queries, daily_compute, concurrency, busy, budget_exhausted, engine_unavailable, bad_sql, not_read_only, sql_error, not_allowed, timeout, out_of_memory, bad_format, bad_limit, bad_date, no_such_table, not_found.

  • message string required

    What went wrong and what to do, in plain words.

  • get_a_key string (uri)

    On 401: where to get a key.

  • docs string (uri)

    On 401: the API guide.

Example (503)
{
"error": "unauthorized",
"message": "Send an API key: `Authorization: Bearer tl_live_…`. Get a free key at https://transitlab.nyc/api-keys.",
"get_a_key": "https://transitlab.nyc/api-keys",
"docs": "https://docs.transitlab.nyc/start/sql-api/"
}