Skip to content

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.

event_type
string

Only events of exactly this type, such as login.failed. GET /admin/audit/event_types lists the types in the log.

actor_user_ref
integer format: int64

Only events done by this user (numeric user ref).

subject_user_ref
integer format: int64

Only events that happened to this user (numeric user ref).

since
string format: date-time

Only events at or after this time.

until
string format: date-time

Only events at or before this time.

limit
integer
default: 100 >= 1 <= 500
cursor
string

A page of events and the total that match.

object
items
required
Array<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
id
required
string format: uuid
event_type
required
string
occurred_at
required
string format: date-time
subject_user_ref

Who it happened to, as a numeric user ref. Left out when the event isn’t about a user.

integer format: int64
nullable
actor_user_ref

Who did it, as a numeric user ref. Left out for system events and anonymous requests.

integer format: int64
nullable
ip

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.

string
nullable
user_agent
string
nullable
metadata
required

Details of the event. The keys depend on event_type and don’t follow a fixed schema.

object
key
additional properties
any
total
required

How many events match the filters, ignoring the cursor. 0 if the count failed.

integer format: int64
next_cursor
string
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed