Count audit events over time (admin)
/v1/admin/orgs/{slug}/audit-events/countsReturns how many audit records match, per time bucket and optionally per
value of one column, as a dense, zero-filled UTC series. It takes exactly
the audit list's filters, so the counts are the records the list pages
through for the same parameters — except that reads of the audit log
itself are left out unless include_audit_reads is set, so a
dashboard's own reads do not dominate the chart drawn from them.
bucket is one of a fixed list, each allowed up to a window: 1m up to
2 hours, 10m up to 2 days, 1h up to 31 days and 1d up to the 90-day
maximum x-window declares. Omitted, it is the finest the window allows.
The window is widened to whole buckets and echoed. A window longer than
the bucket asked for allows is refused with window_too_large, and an
answer of more than 32768 counts — series times buckets — with
too_many_series.
Answers are cached per organization, read scope, permission projection,
filters, bucket and window for at least the dashboard's shortest refresh
interval, and replicas sharing a cache compute each one once. An
aggregate runs under a deadline and a per-server concurrency cap; past
either it is answered 503 busy with Retry-After rather than queued.
Requires the nauthera.insights:read scope and the insights.read
permission. Every filter that names a principal, a session or a request
— actor_id, target_id, session_id, request_id, trace_id — and
grouping by action additionally require audit.read, and client_ip
also users.pii.read, so counts never become a per-user or per-address
record for a caller who may see only aggregates. Reading counts is
recorded at the trace level only, so polling adds nothing to the audit
log at the levels a deployment usually runs.
The organization slug. It names the TENANT OF RECORD for the operation: the rows it reads and writes, the policy its secrets are derived under, and the organization its audit record is filed against all come from this organization. A token is admitted only through its own slug, except a main-org token, which may be admitted through any — so cross-tenant administration is performed through the TARGET tenant's slug, never by naming its resources through another. A token reaching for a slug it may not be admitted through is refused identically whether that organization exists or not.
1–64 characters
- bucketenum
The bucket length. Omitted, the finest the window allows.
Possible values"1m""10m""1h""1d" - group_byenum
The column to split the counts by. Omitted, one series.
Possible values"action""category""outcome""severity""reason""client""actor_type" - include_audit_readsboolean
Count reads of the audit log too.
- fromstring · date-time
Inclusive start of the window (RFC3339). Defaults to 30 days before
to.The window from
fromtotomay span at most 90 days. - tostring · date-time
Exclusive end of the window (RFC3339). Defaults to now.
The window from
fromtotomay span at most 90 days. - actionarray of strings
Action patterns, comma-separated.
*and?are wildcards and do not stop at a dot, souser.*coversuser.password.changedas well asuser.created. A pattern matching no known action simply returns nothing, and an empty element is ignored. With no pattern, every action butsystem.audit.checkpointis counted: the hash chain's checkpoint records, which the verifier reads, are counted only for a pattern that matches them.at most 32 items · each item: at most 128 characters · each item: pattern
^[a-z0-9_.*?-]*$ - categoryarray of enums
Categories, comma-separated.
Possible values"authentication""session""mfa""token""user""organization""client""role""admin""audit""system"at most 16 items
- outcomearray of enums
Outcomes, comma-separated.
Possible values"success""failure""denied""error"at most 16 items
- severityarray of enums
Severities, comma-separated.
Possible values"info""notice""warning""critical"at most 16 items
- actor_idstring
Only records caused by this principal.
at most 256 characters
- target_idstring
Only records acting on this object.
at most 256 characters
- target_typeenum
The kind of object an event acted upon.
audit_logis the log itself, for the events that record reading or exporting it.consentis one user's standing agreement with one client for one resource, named by the agreement's id, so every decision about it shares one target.Possible values"user""organization""client""session""token""factor""role""system""audit_log""consent" - client_ipstring
at most 64 characters
- client_idstring
at most 256 characters
- session_idstring
at most 256 characters
- request_idstring
The
X-Request-IDof a single request. This andtrace_idare what a support engineer arrives with.at most 256 characters
- trace_idstring
at most 64 characters
- cross_tenant_onlyboolean
Only actions taken on this organization by an actor from another one. It is the single most useful security view a multi-tenant audit log offers, which is why it is a first-class filter.
- DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's
cnf.jktand cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.
200 OKapplication/jsonThe counts.
The counts.
Headers
Cache-Controlno-store
Body
How many audit records matched, per bucket of the window and per group: a dense, zero-filled UTC series. The window is the one asked for widened to whole buckets, and is echoed so a chart labels exactly the buckets it was given.
Show moreShow less
This is the bounded exception to the audit list's no-total rule: the bucket lengths and their windows are a fixed list, the series times the buckets of one answer are capped, and an answer is cached per caller view for at least the dashboard's shortest refresh interval.
The first bucket's start.
The last bucket's end.
A bucket length counts are grouped by, each allowed up to a window:
1mup to 2 hours,10mup to 2 days,1hup to 31 days and1dup to the 90-day maximum. Buckets are UTC, a day's included.Possible values"1m""10m""1h""1d"One series per group, ordered by key. Ungrouped counts are a single series with an empty key; grouped counts carry a series only for the groups that matched something.
Each item:One group's counts, one per bucket of the window, in order.
Show item attributesHide item attributes
- group_byenum
The column counts are split by.
clientis the record's client id andactor_typeits actor's type; the rest are the record's own fields of that name. Grouping byactionadditionally requiresaudit.read.Possible values"action""category""outcome""severity""reason""client""actor_type"
400 Bad Requestapplication/problem+jsonThe query was invalid: a malformed window, an unknown vocabulary value or pattern, a window longer than the bucket allows (
window_too_large), or an answer that would carry too many series (too_many_series).The query was invalid: a malformed window, an unknown vocabulary value or pattern, a window longer than the bucket allows (
window_too_large), or an answer that would carry too many series (too_many_series).Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
401 Unauthorizedapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
403 Forbiddenapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
503 Service Unavailableapplication/problem+jsonThe server is computing as many aggregates as it allows at once, or this one did not finish within its deadline (
busy); retry after Retry-After. Also answered when audit logging is not enabled (unavailable).The server is computing as many aggregates as it allows at once, or this one did not finish within its deadline (
busy); retry after Retry-After. Also answered when audit logging is not enabled (unavailable).Headers
Retry-Afterstring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the suffix oftype), so consumers can branch on it without parsing prose.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"urn:problem-type:validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error" - instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"