16.1.1.22. Monitoring endpoints¶

The monitoring REST API exposes time-series statistics that privacyIDEA collects via its monitoring module (e.g. token counts, success/failure rates, audit volume). Which keys are available depends on the active monitoring module (see Monitoring parameters) and on event handlers that emit Counter actions.

All endpoints require admin authentication. Reading is gated by the admin policy action statistics_read, deletion by statistics_delete.

GET /monitoring/(stats_key)¶

GET /monitoring/¶

Return statistics from the monitoring store. The behavior depends on whether stats_key is given as a path component:

without a key — return the list of all statistics keys currently stored on the server.
with a key — return a list of [timestamp, value] pairs for that key, ordered by timestamp ascending. Timestamps are strings in the format %Y-%m-%d %H:%M:%S.%f%z.

The start and end query parameters restrict the time window (inclusive on both ends). Always send timezone-aware datetimes; otherwise the server will interpret naive timestamps as its own local time, which typically yields unexpected results. Example: 2010-12-31 22:00+0200.

Requires admin authentication and the policy action statistics_read.

Parameters:

stats_key – optional path component selecting a single key.

Query Parameters:

start – lower bound of the time window (timezone-aware).
end – upper bound of the time window (timezone-aware).

Status Codes:

200 OK – list of keys, or list of [timestamp, value] pairs.

DELETE /monitoring/(stats_key)¶

Delete entries for the given statistics key. Without start or end, all entries for the key are removed; otherwise only entries within the given time window are deleted.

Always send timezone-aware datetimes for start / end. If they are sent without a timezone, the server will interpret them as its own local time, which typically yields unexpected deletions. Example: 2010-12-31 22:00+0200.

Requires admin authentication and the policy action statistics_delete.

Parameters:

stats_key – path component, the key whose data should be deleted.

Query Parameters:

start – lower bound of the time window (timezone-aware, inclusive).
end – upper bound of the time window (timezone-aware, inclusive).

Status Codes:

200 OK – number of deleted entries in result.value.

GET /monitoring/(stats_key)/last¶

Return the most recent value stored for the given statistics key.

Requires admin authentication and the policy action statistics_read.

Parameters:

stats_key – path component, the key to query.

Status Codes:

200 OK – the scalar value in result.value, or null if no data exists for the key.