AUDIT_LOG_API.md

Audit log API

The core.audit.entry.list action returns audit entries in reverse chronological order. It requires an authenticated request with the view_audit_logs permission and uses a request-rate cost of 3.

Request

{
  "action": "core.audit.entry.list",
  "token": "<token>",
  "nonce": "<unique nonce>",
  "timestamp": 1786600000,
  "data": {
    "page_size": 50,
    "cursor": null,
    "filters": ["core.auth.login", "core.directory.create"],
    "exclude_filters": ["core.audit.entry.list", "core.setting.get"]
  }
}

All fields in data are optional:

Field	Type	Behavior
page_size	integer	Number of entries to return, from 1 through 128. Defaults to 128.
cursor	string or null	Opaque cursor returned by the previous page.
filters	array of strings	Exact audit action values combined with OR. An omitted or empty array does not restrict included actions.
exclude_filters	array of strings	Excludes exact action values. An omitted or empty array excludes nothing. Exclusion wins when a value appears in both lists.

Unknown action values are valid. An unknown inclusion produces no matches; an unknown exclusion removes nothing. Action values are the strings emitted by the server and its extensions; they are not a closed enum.

Response data

{
  "items": [
    {
      "id": "<audit entry id>",
      "action": "core.directory.create",
      "user_id": "<user UUID>",
      "target": null,
      "data": null,
      "result": 0,
      "remote_address": "192.0.2.10",
      "logged_time": 1786600000.25
    }
  ],
  "page_size": 50,
  "next_cursor": "<opaque cursor>",
  "has_more": true
}

Entries are ordered by logged_time descending and then id descending. The cursor expires after one hour and is bound to the action and filter values used to create it. Clients must repeat the same filters values when requesting the next page, together with the same exclude_filters. Ordering and duplicates in either list do not affect the cursor, but adding or removing a distinct value causes the server to reject the cursor with response code 400.

Since protocol 28, user management actions record the target account UUID in target and, once resolved, its name snapshot in data.target_username. user_id identifies the actor. Resource actions keep their resource ID target and may include the owner in data.target_user_id. Credential authentication events still use username targets, and historical entries keep their original target format. See account identity.

When there is no next page, has_more is false and next_cursor is null. The cursor is internal and must be replayed without decoding or modifying it.