---
title: Jobs API
description: List and inspect jobs, stream state changes, cancel eligible work, and remint result links.
species: reference
---
# Jobs API

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

## List jobs

```endpoint
GET /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

```endpoint
GET /jobs/{id}
```

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

```endpoint
GET /jobs/{id}/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

```endpoint
GET /jobs/{id}/result
```

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

## Cancel

```endpoint
POST /jobs/{id}/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.