# Jobs API

> Read the jobs and workflows deployed to an environment: their version, retry settings, schedules and recent run counts.

Source: https://galley.themes.dev/docs/reference/jobs-api/

Jobs and workflows are defined in your code and registered by `runnel deploy`, so the API only reads them. Use these endpoints to check what is live in an environment, to build an internal status page, or to confirm a deploy in CI before you send traffic to it. Authentication, errors and rate limits work as in the [Runs API](/docs/reference/runs-api/).

Each job object has these fields:

| Field | Type | Description |
|---|---|---|
| `name` | string | The name given in code, such as `send-invoice`. |
| `kind` | string | `job` or `workflow`. |
| `version` | string | The deploy that last changed it, such as `v42`. |
| `retries` | object | `attempts`, `backoff`, `initial_delay`, `max_delay`. |
| `timeout` | string | Time limit for one attempt, such as `2m`. |
| `concurrency` | object or null | `limit`, and `keyed: true` when the limit applies per key. |
| `schedules` | array | Schedules that start this job: `name`, `cron`, `timezone`, `paused`. |
| `stats_24h` | object | Run counts by status over the last 24 hours. |

## List jobs

Lists every job and workflow in the key's environment, sorted by name. Most projects fit on one page; pagination works with `cursor` as elsewhere.

`GET /v1/jobs`

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `kind` | string | No | Only `job` or only `workflow`. |
| `limit` | integer | No | Page size, 1 to 100. Defaults to 50. |
| `cursor` | string | No | Cursor from the previous page. |

```bash
curl "https://api.runnel.example/v1/jobs?kind=workflow" \
  -H "Authorization: Bearer $RUNNEL_API_KEY"
```

```json
{
  "data": [
    {
      "name": "onboard-customer",
      "kind": "workflow",
      "version": "v42",
      "timeout": "15m",
      "schedules": [],
      "stats_24h": { "succeeded": 1288, "failed": 3, "running": 14 }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Retrieve a job

Returns one job or workflow by name, with its full settings and schedules.

`GET /v1/jobs/{name}`

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | The job's name, in the path. |

```bash
curl https://api.runnel.example/v1/jobs/usage-report \
  -H "Authorization: Bearer $RUNNEL_API_KEY"
```

```json
{
  "name": "usage-report",
  "kind": "job",
  "version": "v41",
  "retries": { "attempts": 3, "backoff": "exponential", "initial_delay": "5s", "max_delay": "5m" },
  "timeout": "10m",
  "concurrency": { "limit": 1, "keyed": false },
  "schedules": [
    { "name": "nightly-usage", "cron": "0 2 * * *", "timezone": "Europe/London", "paused": false }
  ],
  "stats_24h": { "succeeded": 1, "failed": 0, "running": 0 },
  "last_run_at": "2026-10-28T02:00:00Z"
}
```

A job that is not in the environment returns `404` with the error type `not_found`. That usually means the deploy went to another environment; `runnel env list` shows which version each one runs.

> **Tip** In CI, call this endpoint after `runnel deploy` and compare `version` with the one the deploy printed. It catches a deploy that went to the wrong environment before any runs do.