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.

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.

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

{
  "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.

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

{
  "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.