Findings across every run — the WebUI's All-findings screen.
const url = 'https://example.com/api/v1/analysis/findings';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page cursor: the at of the previous page’s last row (RFC 3339).
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”.
Inclusive lower bound on finding time, RFC 3339 — the range filter, not the cursor.
Comma-separated diagnostics (AnalysisTool tokens, e.g. anomaly,capacity); empty or
absent means every tool. An unknown token is rejected rather than ignored.
Comma-separated severities (crit, warn, info); empty or absent means every severity.
Case-insensitive substring of the metric name or the finding kind — the two halves the What column shows.
Restrict to findings about one node.
Case-insensitive substring of the node’s current name. Distinct from node_id, which names
exactly one node; fleet-wide findings never match this.
Restrict to findings about nodes in one folder group and everything beneath it.
Inclusive lower bound on the finding’s score. One-sided is the usual shape — “8 or worse”.
Inclusive upper bound on the finding’s score.
Page size, clamped to 200 (default 100).
Responses
Section titled “Responses”Matching findings, newest first; empty when this deployment has no runner
One finding as the cross-run search returns it: the finding, plus the run it came from.
object
When the finding was written (RFC 3339). Pass it back as before, with id as
before_id, to fetch the next page.
The analysis run that produced this finding.
The node this finding is about; absent for a fleet-level finding.
crit, warn or info.
Which diagnostic produced it, as that run recorded it (e.g. anomaly).
Examplegenerated
[ { "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" }]A cursor or range bound is not RFC 3339, or the tool/severity is unknown
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}No valid bearer token
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role lacks the read permission
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}The requested node or group filter is outside the caller’s scope
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}