Fleet passive-event summary aggregates for the dashboard widgets.

GET

/api/v1/events/stats

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

• bearer

Parameters

Query Parameters

start

string

end

string

kind

string

Event kinds to include, comma-separated; empty or absent means every kind.

node_id

string format: uuid

matched

boolean

action

string

Rule outcomes to include, comma-separated; empty or absent means all.

severity

string

Syslog severities (0–7) to include, comma-separated; empty or absent means all.

q

string

regex

boolean

msg

string

Message-only condition (see GET /events).

msg_regex

boolean

Interpret msg as a regular expression.

msg_not

boolean

Keep the events whose message does not match msg.

src

string

Condition on the event’s source IP or attributed node name (see GET /events).

src_not

boolean

Keep the events whose source does not match src.

group_by

string

limit

integer format: int64

bucket_secs

integer format: int64

split

string

Responses

200

A volume series for group_by=time, count-ordered buckets otherwise

Media typeapplication/json

One of:

Array<object>

group_by=time: the volume series.

Array<object>

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

by_kind

object | null

count

required

integer format: int64

ts_unix_ms

required

integer format: int64

Array<object>

Every other group_by: count-ordered categorical buckets.

Array<object>

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

count

required

integer format: int64

key

required

string

label

string | null

node_id

string | null format: uuid

Example^generated

[
  {
    "by_kind": "example",
    "count": 1,
    "ts_unix_ms": 1
  }
]

400

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

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

503

This deployment has no write side to resolve node names against

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