List audit events
GET /admin/audit
Lists audit events, newest first: sign-ins and failed sign-ins, account and capability changes, admin settings changes, federation admin actions and other security events. This is the audit log, not the activity log.
Events are recorded on a best-effort basis: a failed write is noted only in the server log, so the log can have gaps, and not every action is audited.
ip is returned only if you also hold system.audit.pii.read. It’s
the only field held back: user agents and metadata come back to
anyone who can read the log, and metadata can include usernames,
email addresses and, for login.rate_limited events, the client’s
IP address.
Filters are optional and combine with AND. An empty event_type
counts as no filter. limit defaults to 100; 0 or less also gives
100, and more than 500 gives 500. For the next page, pass
next_cursor back as cursor; it’s left out on the last page. A
cursor that can’t be read is ignored, and you get the newest page
again.
Each page also carries total, a separate count of all matching
events that ignores the cursor, so it can drift from the pages you
read as events arrive. If the count fails, total is 0 even though
items has events.
A nightly job deletes events past their retention period: seven
years by default, set per category (the part of event_type before
the first dot). Events under legal hold are kept. You need
system.audit.read or system.admin.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Only events of exactly this type, such as login.failed. GET /admin/audit/event_types lists the types in the log.
Only events done by this user (numeric user ref).
Only events that happened to this user (numeric user ref).
Only events at or after this time.
Only events at or before this time.
Responses
Section titled “ Responses ”A page of events and the total that match.
object
One audit event. id, event_type, occurred_at and metadata
are always present; the other fields are left out when the event has
no value for them.
object
Who it happened to, as a numeric user ref. Left out when the event isn’t about a user.
Who did it, as a numeric user ref. Left out for system events and anonymous requests.
The address the request came from: the first X-Forwarded-For entry
if the request had one, otherwise the connection’s address. Returned
only if you also hold system.audit.pii.read (or system.admin);
otherwise it’s left out, so a missing ip can also mean none was
recorded.
Details of the event. The keys depend on event_type and don’t follow a fixed schema.
object
How many events match the filters, ignoring the cursor. 0 if the count failed.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed