Guild audit logs
An audit log entry records one change to a guild and who made it. You get entries with List guild audit logs or its Admin API counterpart. Entries are kept for 45 days.
Each new entry is also sent as Guild Audit Log Entry Create to sessions with VIEW_AUDIT_LOG.
Audit log reason
Section titled “Audit log reason”A route marked Audit reason accepts the X-Audit-Log-Reason header, listed with the standard request headers. The value is trimmed and used as sent, with no percent-decoding. A blank value or one over 512 characters is dropped and the request still succeeds.
When the header is absent, Create or replace guild ban uses the body reason, and Modify guild member uses timeout_reason if the body sets communication_disabled_until. Bot additions, message deletions made by Delete message attachment and entries made by message deletion consolidation never have a reason.
Guild audit log response object
Section titled “Guild audit log response object”One page of entries with the users, webhooks and threads they reference.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| audit_log_entries | array[guild audit log entry object] | The page of entries |
| users | array[partial user object] | The users the entries reference |
| webhooks | array[audit log webhook object] | The webhooks that webhook entries target and that still exist |
| threads?1 | array[thread object] | The threads that thread entries target and that still exist |
1 Present only for a bot and for a user session that declares the channel_threads client capability
users has every user an entry was made by or refers to. A deleted user is returned as DeletedUser.
Guild audit log entry object
Section titled “Guild audit log entry object”One change to the guild.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the entry |
| action_type | integer | The audit action |
| user_id1 | snowflake | The ID of the user that did the action |
| target_id2 | ?string | The ID of the affected entity |
| reason? | string | The audit log reason |
| options? | audit log options object | The options the action records |
| changes? | array[audit log change object] | The fields the action changed |
1 0, the system user, when Fluxer made the change itself. That covers a member removal, ban or unban by an instance admin through the Admin API, an automatic invite pause and a managed role update
2 The invite code for INVITE_CREATE and INVITE_DELETE, and null for MESSAGE_BULK_DELETE
Example
Section titled “Example”{ "id": "1501314428688998184", "action_type": 24, "user_id": "1489002177550843905", "target_id": "1489002177550843906", "reason": "Nickname violated the rules", "changes": [{"key": "nick", "old_value": "spam bot", "new_value": null}]}Audit actions
Section titled “Audit actions”Each value is an action_type, and the action_type query filter takes the same values. An update or a member move records an entry only when something changed. For GUILD_UPDATE, a change to only guild_id, member_count or an image width or height records nothing.
| Value | Name | Description |
|---|---|---|
| 1 | GUILD_UPDATE | Guild settings, custom invite URL or ownership changed. target_id is the guild |
| 10 | CHANNEL_CREATE | Channel created. target_id is the channel and the option is type |
| 11 | CHANNEL_UPDATE | Channel changed. target_id is the channel and the option is type |
| 12 | CHANNEL_DELETE | Channel deleted. target_id is the channel and the option is type |
| 13 | CHANNEL_OVERWRITE_CREATE1 | Permission overwrite created. target_id is the role or member |
| 14 | CHANNEL_OVERWRITE_UPDATE1 | Permission overwrite changed. target_id is the role or member |
| 15 | CHANNEL_OVERWRITE_DELETE1 | Permission overwrite deleted. target_id is the role or member |
| 20 | MEMBER_KICK | Member removed by a moderator. target_id is the user |
| 21 | MEMBER_PRUNE2 | Inactive members pruned |
| 22 | MEMBER_BAN_ADD | Ban created or replaced. target_id is the user and the option is delete_message_seconds |
| 23 | MEMBER_BAN_REMOVE | Ban removed. target_id is the user |
| 24 | MEMBER_UPDATE | Member changed. target_id is the user |
| 25 | MEMBER_ROLE_UPDATE | One role added to or removed from a member. target_id is the user and the option is role_name |
| 26 | MEMBER_MOVE3 | Member moved to another voice channel. target_id is the user |
| 27 | MEMBER_DISCONNECT3 | Member disconnected from voice. target_id is the user |
| 28 | BOT_ADD | Bot added. target_id is the user and the option is temporary |
| 30 | ROLE_CREATE | Role created. target_id is the role |
| 31 | ROLE_UPDATE | Role changed. target_id is the role and the option is role_name |
| 32 | ROLE_DELETE | Role deleted. target_id is the role |
| 40 | INVITE_CREATE4 | Invite created. target_id is the invite code |
| 41 | INVITE_UPDATE2 | Invite changed. target_id is the invite code |
| 42 | INVITE_DELETE4 | Invite deleted. target_id is the invite code |
| 50 | WEBHOOK_CREATE5 | Webhook created. target_id is the webhook and the options are channel_id and type |
| 51 | WEBHOOK_UPDATE | Webhook changed. target_id is the webhook and the options are channel_id and type |
| 52 | WEBHOOK_DELETE5 | Webhook deleted. target_id is the webhook and the options are channel_id and type |
| 60 | EMOJI_CREATE | Emoji created. target_id is the emoji |
| 61 | EMOJI_UPDATE | Emoji changed. target_id is the emoji |
| 62 | EMOJI_DELETE | Emoji deleted. target_id is the emoji |
| 72 | MESSAGE_DELETE | Message deleted. target_id is the message and the option is channel_id |
| 73 | MESSAGE_BULK_DELETE | Messages deleted together. target_id is null and the options are channel_id and count |
| 74 | MESSAGE_PIN | Message pinned. target_id is the message and the options are channel_id and message_id |
| 75 | MESSAGE_UNPIN | Message unpinned. target_id is the message and the options are channel_id and message_id |
| 90 | STICKER_CREATE | Sticker created. target_id is the sticker |
| 91 | STICKER_UPDATE | Sticker changed. target_id is the sticker |
| 92 | STICKER_DELETE | Sticker deleted. target_id is the sticker |
| 110 | THREAD_CREATE | Thread created. target_id is the thread |
| 111 | THREAD_UPDATE | Thread changed. target_id is the thread and the option is type |
| 112 | THREAD_DELETE | Thread deleted. target_id is the thread and the option is type |
1 The options are id, type, channel_id and role_name, and role_name is recorded only for a role other than @everyone
2 Never recorded. The filter still accepts it
3 The options are channel_id and count, and count is always 1. channel_id is the new channel for a move and the channel the member left for a disconnect
4 The options are max_age, max_uses, temporary, channel_id and inviter_id, and the last two are recorded only when the invite has them
5 Follow announcement channel records these in the guild that follows the channel, with type 2
Deleting a channel deletes its threads and records only CHANNEL_DELETE.
Audit log options object
Section titled “Audit log options object”An action records only the options listed for it in audit actions, and options is omitted when it has none.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| channel_id | string | The ID of the channel the action concerns |
| count | number | The number of entities the action affected |
| delete_member_days1 | string | The whole days of messages a ban deleted |
| delete_message_seconds | number | The seconds of messages a ban deleted, present when positive |
| id | string | The ID of the role or member an overwrite applies to |
| integration_type2 | number | The type of the integration |
| inviter_id | string | The ID of the user that created the invite |
| max_age | number | The invite lifetime in seconds |
| max_uses | number | The maximum use count of the invite |
| members_removed2 | number | The number of memberships the action removed |
| message_id | string | The ID of the message the action concerns |
| role_name | string | The name of the role when the entry was written |
| temporary | boolean | Whether the invite or bot membership is temporary |
| type | number | The channel type, permission overwrite type or webhook type |
| uses2 | number | The use count of the invite |
1 Present only on older ban entries, which have no delete_message_seconds
2 Never recorded
Audit log change object
Section titled “Audit log change object”One field an action changed. A creation has only new_value, a deletion has only old_value, and a modification has both.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| key | string | The name of the field that changed, from the change fields of the target |
| old_value? | audit log change value | The value before the change |
| new_value? | audit log change value | The value after the change |
A change value is a string, number, boolean, null, an array of strings or numbers, or an object with added and removed string arrays. Permission masks and snowflakes are decimal strings. An update lists only the fields that differ.
Change fields
Section titled “Change fields”Guild change fields
Section titled “Guild change fields”Recorded by GUILD_UPDATE.
| Field | Type | Description |
|---|---|---|
| guild_id | string | The ID of the guild |
| name | string | The name of the guild (1-100 characters) |
| owner_id | string | The ID of the guild owner |
| vanity_url_code | ?string | The custom invite code |
| icon_hash | ?string | The guild icon hash |
| banner_hash | ?string | The guild banner hash |
| banner_width | ?number | The guild banner width in pixels |
| banner_height | ?number | The guild banner height in pixels |
| splash_hash | ?string | The guild splash hash |
| splash_width | ?number | The guild splash width in pixels |
| splash_height | ?number | The guild splash height in pixels |
| splash_card_alignment | number | The splash card alignment |
| embed_splash_hash | ?string | The guild embed splash hash |
| embed_splash_width | ?number | The guild embed splash width in pixels |
| embed_splash_height | ?number | The guild embed splash height in pixels |
| features | array[string] | The guild features sorted |
| verification_level | number | The verification level |
| mfa_level | number | The MFA level |
| nsfw_level | number | The NSFW level |
| nsfw | boolean | Whether the guild is marked age restricted |
| content_warning_level | number | The guild content warning level |
| content_warning_text | ?string | The content warning text |
| explicit_content_filter | number | The guild explicit content filter level |
| default_message_notifications | number | The default message notification level |
| system_channel_id | ?string | The ID of the system channel |
| system_channel_flags | number | The system channel flags mask |
| rules_channel_id1 | ?string | The ID of the rules channel |
| afk_channel_id | ?string | The ID of the AFK voice channel |
| afk_timeout | number | The AFK timeout in seconds |
| disabled_operations1 | number | The disabled guild operations mask |
| member_count1 | number | The member count |
| message_history_cutoff | ?ISO8601 timestamp | The message history cutoff |
1 Never recorded
Channel change fields
Section titled “Channel change fields”Recorded by CHANNEL_CREATE, CHANNEL_UPDATE and CHANNEL_DELETE.
| Field | Type | Description |
|---|---|---|
| channel_id | string | The ID of the channel |
| type | number | The channel type |
| name | ?string | The name of the channel |
| topic | ?string | The topic of the channel |
| url1 | ?string | The destination URL of the channel |
| parent_id | ?string | The ID of the parent category, or null for a top-level channel |
| position | number | The position of the channel among its siblings |
| nsfw | ?boolean | Whether the channel is marked age restricted, or null when it has no override |
| content_warning_level | number | The content warning level |
| content_warning_text | ?string | The content warning text |
| rate_limit_per_user | number | The slowmode interval in seconds |
| user_limit | ?number | The voice occupancy limit |
| voice_connection_limit | ?number | The per-user voice connection limit |
| bitrate | ?number | The voice bitrate in bits per second |
| rtc_region | ?string | The pinned voice region, or null when the channel is routed automatically |
| rtc_p2p | boolean | Whether the channel is pinned to peer-to-peer voice |
| permission_overwrite_count2 | number | The number of permission overwrites the channel has |
| flags3 | number | The channel flags of the channel |
| default_auto_archive_duration3 | number | The stored default auto archive duration |
| default_thread_rate_limit_per_user3 | number | The slowmode interval in seconds new threads inherit |
| available_tags3 | array[forum tag object] | The tags a post can apply |
| default_reaction_emoji3 | default reaction object | The reaction clients show on each post |
| default_sort_order3 | number | The default sort order of posts |
| default_forum_layout3 | number | The default layout of posts |
| default_tag_setting3 | string | The default tag matching of a post search |
1 Recorded only for a GUILD_LINK channel type
2 Never recorded. Each overwrite change gets its own permission overwrite entry
3 Recorded only by CHANNEL_CREATE and CHANNEL_UPDATE, for channels with thread or forum settings
Thread change fields
Section titled “Thread change fields”Recorded by THREAD_CREATE, THREAD_UPDATE and THREAD_DELETE.
| Field | Type | Description |
|---|---|---|
| name | string | The name of the thread |
| type | number | The thread type |
| archived | boolean | Whether the thread is archived |
| locked | boolean | Whether the thread is locked |
| auto_archive_duration | number | The auto archive duration in minutes |
| rate_limit_per_user | number | The slowmode interval in seconds |
| flags | number | The channel flags of the thread |
| invitable1 | boolean | Whether members who are not thread moderators can add people to the thread |
| applied_tags2 | array[string] | The IDs of the applied forum tags |
1 Recorded only for a private thread
2 Recorded only for a thread whose parent is a forum or media channel
Permission overwrite change fields
Section titled “Permission overwrite change fields”Recorded by CHANNEL_OVERWRITE_CREATE, CHANNEL_OVERWRITE_UPDATE and CHANNEL_OVERWRITE_DELETE, and every value is a string.
| Field | Type | Description |
|---|---|---|
| id | string | The ID of the role or member the overwrite applies to |
| type | string | The permission overwrite type |
| allow | string | The permission mask the overwrite grants |
| deny | string | The permission mask the overwrite denies |
Guild member change fields
Section titled “Guild member change fields”Recorded by MEMBER_UPDATE and MEMBER_ROLE_UPDATE.
| Field | Type | Description |
|---|---|---|
| user_id | string | The ID of the member |
| nick | ?string | The member's nickname in this guild |
| roles | array[string] | The role IDs of the member, sorted |
| avatar_hash | ?string | The guild avatar hash |
| banner_hash | ?string | The guild banner hash |
| bio | ?string | The guild profile bio |
| pronouns | ?string | The guild profile pronouns |
| accent_color | ?number | The guild profile accent color |
| deaf | boolean | Whether a moderator has deafened the member |
| mute | boolean | Whether a moderator has muted the member |
| communication_disabled_until | ?ISO8601 timestamp | The time the communication restriction expires, or null when the member is not restricted |
| temporary | boolean | Whether the membership is temporary |
Voice move change fields
Section titled “Voice move change fields”Recorded by MEMBER_MOVE and MEMBER_DISCONNECT.
| Field | Type | Description |
|---|---|---|
| channel_id1 | string | The ID of the voice channel |
1 A move has the previous channel as old_value and the destination as new_value, and a disconnect has only old_value
Guild ban change fields
Section titled “Guild ban change fields”Recorded by MEMBER_BAN_ADD and MEMBER_BAN_REMOVE.
| Field | Type | Description |
|---|---|---|
| user_id | string | The ID of the banned user |
| moderator_id | string | The ID of the user that issued the ban |
| banned_at | ISO8601 timestamp | The time the ban was issued |
| expires_at | ?ISO8601 timestamp | The expiry of a temporary ban, or null for a permanent ban |
| reason1 | ?string | The stored ban reason |
1 The reason stored on the ban, which is the body reason or, without one, the X-Audit-Log-Reason value
Guild role change fields
Section titled “Guild role change fields”Recorded by ROLE_CREATE, ROLE_UPDATE and ROLE_DELETE.
| Field | Type | Description |
|---|---|---|
| role_id | string | The ID of the role |
| name | string | The name of the role (1-100 characters) |
| permissions | string | The permission mask the role grants |
| position | number | The position of the role in the guild hierarchy |
| hoist_position | ?number | The member list position of the role, or null when it uses position |
| color | number | The role color as an integer |
| icon_hash | ?string | The role icon hash |
| unicode_emoji | ?string | The role Unicode emoji |
| hoist | boolean | Whether the role is displayed separately |
| mentionable | boolean | Whether the role is mentionable |
| permissions_diff1 | object | The permission names this change added and removed |
1 Recorded only by Modify guild role when the mask changed, as new_value with no old_value
Invite change fields
Section titled “Invite change fields”Recorded by INVITE_CREATE and INVITE_DELETE.
| Field | Type | Description |
|---|---|---|
| code | string | The code that identifies the invite |
| channel_id | ?string | The ID of the channel the invite points at |
| guild_id | ?string | The ID of the guild the invite belongs to |
| inviter_id | ?string | The ID of the user that created the invite |
| uses | number | The use count |
| max_uses | number | The maximum use count |
| max_age | number | The invite lifetime in seconds |
| temporary | boolean | Whether accepting the invite grants a temporary membership |
| created_at | ISO8601 timestamp | The time the invite was created |
Webhook change fields
Section titled “Webhook change fields”Recorded by WEBHOOK_CREATE, WEBHOOK_UPDATE and WEBHOOK_DELETE.
| Field | Type | Description |
|---|---|---|
| id | string | The ID of the webhook |
| guild_id | ?string | The ID of the guild the webhook belongs to |
| channel_id | ?string | The ID of the channel the webhook posts to |
| name | string | The name the webhook posts under (1-80 characters) |
| creator_id | ?string | The ID of the user that created the webhook |
| avatar_hash | ?string | The webhook avatar hash |
| type | number | The webhook type |
Emoji change fields
Section titled “Emoji change fields”Recorded by EMOJI_CREATE, EMOJI_UPDATE and EMOJI_DELETE.
| Field | Type | Description |
|---|---|---|
| emoji_id | string | The ID of the emoji |
| name | string | The name of the emoji (2-32 characters) |
| animated | boolean | Whether the emoji is animated |
| creator_id | string | The ID of the user that created the emoji |
Sticker change fields
Section titled “Sticker change fields”Recorded by STICKER_CREATE, STICKER_UPDATE and STICKER_DELETE.
| Field | Type | Description |
|---|---|---|
| sticker_id | string | The ID of the sticker |
| name | string | The name of the sticker (2-30 characters) |
| description | ?string | The sticker description |
| animated | boolean | Whether the sticker is animated |
| creator_id | string | The ID of the user that created the sticker |
Audit log webhook object
Section titled “Audit log webhook object”A reduced webhook object without the token, application ID and creator, and with avatar_hash in place of avatar.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the webhook |
| type | integer | The webhook type |
| guild_id | ?snowflake | The ID of the guild containing the webhook |
| channel_id | ?snowflake | The ID of the channel the webhook sends messages to |
| name | string | The name the webhook posts under |
| avatar_hash | ?string | The avatar hash of the webhook |
List guild audit logs
Section titled “List guild audit logs”GET/v1/guilds/{guild_id}/audit-logsReturns one page of audit history as a guild audit log response object, newest first. You need VIEW_AUDIT_LOG.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| limit? | integer | The maximum number of entries to return (0-100, default 50) |
| before? | snowflake | Returns entries older than this entry ID |
| after? | snowflake | Returns entries newer than this entry ID |
| user_id? | snowflake | Returns only entries made by this user |
| action_type? | integer | Returns only entries with this audit action |
Two or more MESSAGE_DELETE entries in a row by the same user in the same channel are replaced by one MESSAGE_BULK_DELETE entry with a new ID and a count. This happens within about a minute of the deletions, and again on any read without user_id or action_type.
A user session without the channel_threads capability gets no entries about threads, forum channels or media channels, and filtering by actions 110 to 112 returns 400.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | guild audit log response object | The page was returned |
| 400 | error response | CANNOT_SPECIFY_BOTH_BEFORE_AND_AFTER when both cursors are sent, or a filter value is invalid |
| 403 | error response | You lack VIEW_AUDIT_LOG |
| 404 | error response | The guild does not exist |
The rate limit is 20 requests per 10 seconds, on the guild:audit_logs::guild_id bucket.