modlog_get

Read the audit log: a record of moderation and admin actions such as bans, role changes, and channel edits. Use it to build an audit log viewer. Results come newest first, one page at a time.

Request

{
  "cmd": "modlog_get",
  "limit": 50,
  "offset": 0,
  "category": "user_moderation",
  "after": 1727000000
}

Field	Type	Required	Description
`limit`	integer	No	Entries per page, from 1 to 200. Defaults to 100.
`offset`	integer	No	How many matching entries to skip. Defaults to 0.
`after`	number or string	No	Unix seconds. Only entries strictly newer than this are returned. A numeric string such as `"1727000000"` also works.
`category`	string	No	Only entries in this category. See categories and actions.
`action`	string	No	Only entries with this action, such as `user_ban`.
`actor`	string	No	Only entries by this user ID. Not a username.
`target`	string	No	Only entries whose `target_id` equals this. What the ID means depends on the action.

Filters combine: an entry must match all of them. An empty string means no filter.

Response

{
  "cmd": "modlog_get",
  "entries": [
    {
      "id": "1727180530204-usr_3kd9a",
      "action": "user_timeout",
      "category": "user_moderation",
      "actor_id": "usr_3kd9a",
      "actor_name": "modbot",
      "target_id": "usr_8f2k1",
      "target_name": "mallory",
      "details": { "duration": 600, "reason": "Spamming links" },
      "timestamp": 1727180530.204
    }
  ],
  "total": 37,
  "offset": 0,
  "limit": 50
}

entries is sorted newest first.
total is the number of entries that match the filters, across all pages. Keep increasing offset by limit until it reaches total.
offset and limit echo the values used.

Each entry has:

Field	Meaning
`id`	Unique entry ID, built from the time in milliseconds and the actor’s ID.
`action`	What happened. Usually the name of the command that did it.
`category`	The group the action belongs to.
`actor_id`, `actor_name`	Who did it. Automod entries use `originChats` and `Automod`.
`target_id`, `target_name`	What it was done to. A user ID, role ID, channel name, report ID, invite code, plugin name, or a fixed word such as `server`, `config`, or `roles`, depending on the action.
`details`	Extra data for the action, such as a reason or the changed fields. The keys vary by action.
`timestamp`	Unix seconds, possibly with a fractional part.

Categories and actions

`category`	`action` values
`user_moderation`	`user_ban`, `user_unban`, `user_kick`, `user_timeout`, `user_update`, `user_sever`, `user_unsever`
`role_management`	`role_create`, `role_update`, `role_delete`, `role_reorder`, `user_roles_set`, `self_role_add`, `self_role_remove`
`channel_management`	`channel_create`, `channel_update`, `channel_move`, `channel_delete`
`message_moderation`	`message_delete`, `report_resolve`, `automod_block`
`server_management`	`server_update`, `server_maintenance`, `config_update`, `access_mode_set`, `server_password_set`, `server_password_remove`, `whitelist_add`, `whitelist_remove`, `invite_create`, `invite_delete`, `application_review`, `application_delete`, `webhook_create`, `webhook_update`, `webhook_delete`, `webhook_regenerate`, `plugin_install`, `plugin_uninstall`, `plugin_enable`, `plugin_disable`, `plugin_reload`, `plugin_file_put`

Some things to know:

message_delete is logged for every deletion, including authors deleting their own messages.
self_role_add and self_role_remove are logged with the member as both actor and target.
Removing a timeout with the /unmute slash command is logged as user_timeout.
Changing a channel’s slow mode or sticky message with a slash command is logged as channel_update.

Retention

Old entries expire. Each category keeps entries for a set number of days:

Category	Default days
`user_moderation`, `role_management`	365
`channel_management`, `server_management`	180
`message_moderation` and anything else	90

Expired entries are deleted from storage the next time anyone reads the log. Server owners can change the limits, or turn logging off with modlog.enabled: false. See audit log settings.

Permissions

Requires view_audit_log or manage_users.

Errors

`val`	When
`limit: Expected at most 200`	`limit` is above 200. Similar messages cover `limit` below 1 and `offset` below 0.
`offset: Expected integer`	`limit` or `offset` has a fractional part.
`category: Expected string, received number`	`category`, `action`, `actor`, or `target` isn’t a string.
`after: Value does not match any union option`	`after` is neither a number nor a string.
`After must be a valid Unix timestamp`	`after` is a string that isn’t a number.
`Modlog storage is unavailable`	The audit log file can’t be read.