Fleet passive-event summary aggregates for the dashboard widgets.
const url = 'https://example.com/api/v1/events/stats';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/events/stats \ --header 'Authorization: Bearer <token>'Categorical (group_by=kind|action|trap|source) returns count-ordered buckets; group_by=time
returns a volume series. Routes to the same store the event log does, so a summary and the list
it summarises can never disagree about which store answered.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Responses
Section titled “Responses”A volume series for group_by=time, count-ordered buckets otherwise
group_by=time: the volume series.
One time bucket for the /events/stats?group_by=time volume series: a bucket-start timestamp
(Unix ms), the total count, and — when split=kind — the per-kind breakdown.
object
Every other group_by: count-ordered categorical buckets.
One categorical /events/stats bucket: a stable key (for the React key + fallback display), an
optional display label resolved server-side (e.g. a trap’s MIB name), an optional node_id
(set for source grouping when the source maps to an inventory node, so the UI resolves its name
— no raw UUID rule), and the row count.
object
Examplegenerated
[ { "by_kind": "example", "count": 1, "ts_unix_ms": 1 }]A range bound is malformed, the kind is unknown, the regex does not compile, or group_by is not one of kind|action|trap|source|time
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" }}This deployment has no write side to resolve node names against
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" }}