Recent analysis jobs (the runs list). `?limit=` (default 50), optionally narrowed.

GET

/api/v1/analysis/jobs

curl --request GET \
  --url https://example.com/api/v1/analysis/jobs \
  --header 'Authorization: Bearer <token>'

Skeleton mode has no runner, so this answers an empty list rather than a 503: the runs list is a panel on a page that otherwise works, and an error there would break the page. The filter is validated before that early return, so a malformed one is a 400 on every deployment rather than an empty 200 on some — a client bug that reads as “no runs” is worse than an error.

Authorizations

• bearer

Parameters

Query Parameters

limit

integer format: int64

tool

string

Only runs of this analysis (e.g. anomaly).

state

string

Only runs in this state: queued | running | done | failed | cancelled. Note done, not succeeded — that is the report-run vocabulary, not this one.

since

string

Only runs started at or after this instant (RFC 3339).

Responses

200

Matching runs, newest first; empty when this deployment has no runner

Media typeapplication/json

Array<object>

A job row, as served to the API / SSE. Timestamps are epoch-millis so the WebUI formats relative times without a date dependency.

object

created_ms

required

integer format: int64

error

string | null

finding_count

required

integer format: int32

finished_ms

integer | null format: int64

id

required

string format: uuid

params

required

pct

required

integer format: int32

phase

string | null

scope_id

string | null format: uuid

scope_kind

required

string

scope_label

required

string

started_ms

integer | null format: int64

state

required

Where an analysis run is in its lifecycle.

A bare String until v0.2.6, and the cost of that was paid twice. The vocabulary had to be written out by hand at the API edge to validate the runs filter, and again in the WebUI to fill its dropdown — two lists nothing compared. Worse, state: string compares equal to any string: the in-app “your analysis finished” notice tested state === 'succeeded', which is the report-run vocabulary, so every successful analysis announced itself as a failure. Typing it makes that comparison a compile error on both sides.

string

Allowed values: queued running done failed cancelled unknown

summary

string | null

tool

required

string

Example

[
  {
    "state": "queued"
  }
]

400

The tool or state is outside its vocabulary, or since is not RFC 3339

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the read permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}