Findings across every run — the Saved-findings screen.

GET

/api/v1/analysis/findings

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

Complements GET /analysis/jobs/{id}/findings, which answers “what did this run find”. This one answers the question an operator actually starts from — “has anything been found about this node / this site / this week” — which no single run can answer because the runs are what get enumerated otherwise.

Skeleton mode has no job store, so it answers an empty list rather than a 503: the screen is a search, and an error where “nothing yet” is the truthful answer reads as a broken page.

Authorizations

• bearer

Parameters

Query Parameters

before

string

Page cursor: the at of the previous page’s last row (RFC 3339).

before_id

string format: uuid

Page cursor tiebreak: that same row’s id. Findings written by one run share a millisecond routinely, so a cursor without it would repeat or skip the rows sharing the boundary instant. Omitting it reads as “strictly before this instant”.

since

string

Inclusive lower bound on finding time, RFC 3339 — the range filter, not the cursor.

tool

string

Restrict to one diagnostic (an AnalysisTool token, e.g. anomaly).

severity

string

Restrict to crit, warn or info.

node_id

string format: uuid

Restrict to findings about one node.

group_id

string format: uuid

Restrict to findings about nodes in one folder group and everything beneath it.

limit

integer format: int64

Page size, clamped to 200 (default 100).

Responses

200

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

Media typeapplication/json

Array<object>

One finding as the cross-run search returns it: the finding, plus the run it came from.

object

at

required

When the finding was written (RFC 3339). Pass it back as before, with id as before_id, to fetch the next page.

string

duration

required

string

id

required

string format: uuid

job_id

required

The analysis run that produced this finding.

string format: uuid

kind

required

string

metric

required

string

node_id

The node this finding is about; absent for a fleet-level finding.

string | null format: uuid

node_name

required

string

score

required

number format: double

severity

required

crit, warn or info.

string

tool

required

Which diagnostic produced it, as that run recorded it (e.g. anomaly).

string

when_label

required

string

Example^generated

[
  {
    "at": "example",
    "duration": "example",
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "job_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "kind": "example",
    "metric": "example",
    "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "node_name": "example",
    "score": 1,
    "severity": "example",
    "tool": "example",
    "when_label": "example"
  }
]

400

A cursor or range bound is not RFC 3339, or the tool/severity is unknown

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"
  }
}

404

The requested node or group filter is outside the caller’s scope

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"
  }
}