Jobs API#

Jobs are the durable record behind asynchronous work. Query jobs expose public statuses queued, running, succeeded, failed, and cancelled.

List jobs#

Returns jobs newest first. limit defaults to 20 and accepts 1–100. When has_more is true, pass next_cursor as starting_after.

Fetch one job#

Returns current status, timestamps, kind, and failure information. A 404 job_not_found does not distinguish an unknown id from a job in another organization.

Follow events#

This Server-Sent Events stream gives each data event a stable increasing id. Reconnect with Last-Event-ID. The stream advertises a 5-second retry, checks durable state every 3 seconds, and sends heartbeat comments every 25 seconds.

Connections close shortly before the 120-second web boundary. Reconnect and always use GET /jobs/{id} as authoritative final state. An invalid event id returns 400 invalid_last_event_id.

Retrieve results#

For a succeeded query job, returns newly signed Parquet URLs valid for 1 hour. Treat those URLs as data-bearing secrets.

Cancel#

Pending work cancels atomically. Running query cancellation is best-effort and may return execution_may_continue: true because work already admitted by the engine can still finish. Poll the job for final state.

GET /version returns the public API contract version advertised in response headers.