Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
24.6 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Guild audit logs
description: Guild audit log entries, audit actions, change fields and the audit log reason header.
---

import RouteHeader from '@/components/RouteHeader.astro';

An audit log entry records one change to a guild and who made it. You get entries with [List guild audit logs](#list-guild-audit-logs) or its [Admin API counterpart](/admin-api/guilds/#list-guild-audit-logs). Entries are kept for 45 days.

Each new entry is also sent as [Guild Audit Log Entry Create](/gateway/events/#guild-audit-log-entry-create) to sessions with `VIEW_AUDIT_LOG`.

## Audit log reason

A route marked Audit reason accepts the `X-Audit-Log-Reason` header, listed with the [standard request headers](/http-api/#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](/http-api/guild-moderation/#create-or-replace-guild-ban) uses the body `reason`, and [Modify guild member](/http-api/guild-members/#modify-guild-member) uses `timeout_reason` if the body sets `communication_disabled_until`. Bot additions, message deletions made by [Delete message attachment](/http-api/messages/#delete-message-attachment) and entries made by [message deletion consolidation](#list-guild-audit-logs) never have a reason.

## Guild audit log response object

One page of entries with the users, webhooks and threads they reference.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| audit_log_entries | array[[guild audit log entry](#guild-audit-log-entry-object) object] | The page of entries |
| users | array[[partial user](/http-api/users/#partial-user-object) object] | The users the entries reference |
| webhooks | array[[audit log webhook](#audit-log-webhook-object) object] | The webhooks that webhook entries target and that still exist |
| threads?<sup>1</sup> | array[[thread](/http-api/threads/#thread-object) object] | The threads that thread entries target and that still exist |

<sup>1</sup> Present only for a bot and for a user session that declares the [`channel_threads` client capability](/http-api/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

One change to the guild.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the entry |
| action_type | integer | The [audit action](#audit-actions) |
| user_id<sup>1</sup> | snowflake | The ID of the user that did the action |
| target_id<sup>2</sup> | ?string | The ID of the affected entity |
| reason? | string | The [audit log reason](#audit-log-reason) |
| options? | [audit log options](#audit-log-options-object) object | The options the action records |
| changes? | array[[audit log change](#audit-log-change-object) object] | The fields the action changed |

<sup>1</sup> `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](/admin-api/), an automatic invite pause and a managed role update

<sup>2</sup> The invite code for [INVITE_CREATE](#audit-actions) and [INVITE_DELETE](#audit-actions), and null for [MESSAGE_BULK_DELETE](#audit-actions)

### Example

```json
{
  "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

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_CREATE<sup>1</sup> | Permission overwrite created. `target_id` is the role or member |
| 14 | CHANNEL_OVERWRITE_UPDATE<sup>1</sup> | Permission overwrite changed. `target_id` is the role or member |
| 15 | CHANNEL_OVERWRITE_DELETE<sup>1</sup> | 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_PRUNE<sup>2</sup> | 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_MOVE<sup>3</sup> | Member moved to another voice channel. `target_id` is the user |
| 27 | MEMBER_DISCONNECT<sup>3</sup> | 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_CREATE<sup>4</sup> | Invite created. `target_id` is the invite code |
| 41 | INVITE_UPDATE<sup>2</sup> | Invite changed. `target_id` is the invite code |
| 42 | INVITE_DELETE<sup>4</sup> | Invite deleted. `target_id` is the invite code |
| 50 | WEBHOOK_CREATE<sup>5</sup> | 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_DELETE<sup>5</sup> | 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` |

<sup>1</sup> The options are `id`, `type`, `channel_id` and `role_name`, and `role_name` is recorded only for a role other than `@everyone`

<sup>2</sup> Never recorded. The filter still accepts it

<sup>3</sup> 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

<sup>4</sup> 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

<sup>5</sup> [Follow announcement channel](/http-api/channels/#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

An action records only the options listed for it in [audit actions](#audit-actions), and `options` is omitted when it has none.

### 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_days<sup>1</sup> | 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_type<sup>2</sup> | 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_removed<sup>2</sup> | 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 |
| uses<sup>2</sup> | number | The use count of the invite |

<sup>1</sup> Present only on older ban entries, which have no `delete_message_seconds`

<sup>2</sup> Never recorded

## 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

| Field | Type | Description |
| --- | --- | --- |
| key | string | The name of the field that changed, from the [change fields](#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

#### Guild change fields

Recorded by [GUILD_UPDATE](#audit-actions).

| 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](/http-api/guilds/#splash-card-alignments) |
| 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](/http-api/guilds/#guild-features) sorted |
| verification_level | number | The [verification level](/http-api/guilds/#verification-levels) |
| mfa_level | number | The [MFA level](/http-api/guilds/#mfa-levels) |
| nsfw_level | number | The [NSFW level](/http-api/guilds/#nsfw-levels) |
| nsfw | boolean | Whether the guild is marked age restricted |
| content_warning_level | number | The [guild content warning level](/http-api/guilds/#guild-content-warning-levels) |
| content_warning_text | ?string | The content warning text |
| explicit_content_filter | number | The [guild explicit content filter level](/http-api/guilds/#guild-explicit-content-filter-levels) |
| default_message_notifications | number | The [default message notification level](/http-api/guilds/#default-message-notification-levels) |
| system_channel_id | ?string | The ID of the system channel |
| system_channel_flags | number | The [system channel flags](/http-api/guilds/#system-channel-flags) mask |
| rules_channel_id<sup>1</sup> | ?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_operations<sup>1</sup> | number | The [disabled guild operations](/http-api/guilds/#disabled-guild-operations) mask |
| member_count<sup>1</sup> | number | The member count |
| message_history_cutoff | ?ISO8601 timestamp | The message history cutoff |

<sup>1</sup> Never recorded

#### Channel change fields

Recorded by [CHANNEL_CREATE](#audit-actions), [CHANNEL_UPDATE](#audit-actions) and [CHANNEL_DELETE](#audit-actions).

| Field | Type | Description |
| --- | --- | --- |
| channel_id | string | The ID of the channel |
| type | number | The [channel type](/http-api/channels/#channel-types) |
| name | ?string | The name of the channel |
| topic | ?string | The topic of the channel |
| url<sup>1</sup> | ?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](/http-api/channels/#content-warning-levels) |
| 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_count<sup>2</sup> | number | The number of permission overwrites the channel has |
| flags<sup>3</sup> | number | The [channel flags](/http-api/forums/#channel-flags) of the channel |
| default_auto_archive_duration<sup>3</sup> | number | The stored default [auto archive duration](/http-api/threads/#auto-archive-durations) |
| default_thread_rate_limit_per_user<sup>3</sup> | number | The slowmode interval in seconds new threads inherit |
| available_tags<sup>3</sup> | array[[forum tag](/http-api/forums/#forum-tag-object) object] | The tags a post can apply |
| default_reaction_emoji<sup>3</sup> | [default reaction](/http-api/forums/#default-reaction-object) object | The reaction clients show on each post |
| default_sort_order<sup>3</sup> | number | The default [sort order](/http-api/forums/#forum-sort-orders) of posts |
| default_forum_layout<sup>3</sup> | number | The default [layout](/http-api/forums/#forum-layouts) of posts |
| default_tag_setting<sup>3</sup> | string | The default [tag matching](/http-api/forums/#forum-tag-settings) of a post search |

<sup>1</sup> Recorded only for a `GUILD_LINK` [channel type](/http-api/channels/#channel-types)

<sup>2</sup> Never recorded. Each overwrite change gets its own [permission overwrite](#permission-overwrite-change-fields) entry

<sup>3</sup> Recorded only by [CHANNEL_CREATE](#audit-actions) and [CHANNEL_UPDATE](#audit-actions), for channels with thread or forum settings

#### Thread change fields

Recorded by [THREAD_CREATE](#audit-actions), [THREAD_UPDATE](#audit-actions) and [THREAD_DELETE](#audit-actions).

| Field | Type | Description |
| --- | --- | --- |
| name | string | The name of the thread |
| type | number | The [thread type](/http-api/threads/#thread-types) |
| archived | boolean | Whether the thread is archived |
| locked | boolean | Whether the thread is locked |
| auto_archive_duration | number | The [auto archive duration](/http-api/threads/#auto-archive-durations) in minutes |
| rate_limit_per_user | number | The slowmode interval in seconds |
| flags | number | The [channel flags](/http-api/forums/#channel-flags) of the thread |
| invitable<sup>1</sup> | boolean | Whether members who are not thread moderators can add people to the thread |
| applied_tags<sup>2</sup> | array[string] | The IDs of the applied [forum tags](/http-api/forums/#forum-tag-object) |

<sup>1</sup> Recorded only for a private thread

<sup>2</sup> Recorded only for a thread whose parent is a forum or media channel

#### Permission overwrite change fields

Recorded by [CHANNEL_OVERWRITE_CREATE](#audit-actions), [CHANNEL_OVERWRITE_UPDATE](#audit-actions) and [CHANNEL_OVERWRITE_DELETE](#audit-actions), 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](/http-api/channels/#permission-overwrite-types) |
| allow | string | The [permission](/http-api/permissions/) mask the overwrite grants |
| deny | string | The [permission](/http-api/permissions/) mask the overwrite denies |

#### Guild member change fields

Recorded by [MEMBER_UPDATE](#audit-actions) and [MEMBER_ROLE_UPDATE](#audit-actions).

| 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

Recorded by [MEMBER_MOVE](#audit-actions) and [MEMBER_DISCONNECT](#audit-actions).

| Field | Type | Description |
| --- | --- | --- |
| channel_id<sup>1</sup> | string | The ID of the voice channel |

<sup>1</sup> 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

Recorded by [MEMBER_BAN_ADD](#audit-actions) and [MEMBER_BAN_REMOVE](#audit-actions).

| 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 |
| reason<sup>1</sup> | ?string | The stored [ban](/http-api/guild-moderation/#guild-ban-object) reason |

<sup>1</sup> The reason stored on the ban, which is the body `reason` or, without one, the `X-Audit-Log-Reason` value

#### Guild role change fields

Recorded by [ROLE_CREATE](#audit-actions), [ROLE_UPDATE](#audit-actions) and [ROLE_DELETE](#audit-actions).

| 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](/http-api/permissions/) 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_diff<sup>1</sup> | object | The permission names this change added and removed |

<sup>1</sup> Recorded only by [Modify guild role](/http-api/permissions/#modify-guild-role) when the mask changed, as `new_value` with no `old_value`

#### Invite change fields

Recorded by [INVITE_CREATE](#audit-actions) and [INVITE_DELETE](#audit-actions).

| 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

Recorded by [WEBHOOK_CREATE](#audit-actions), [WEBHOOK_UPDATE](#audit-actions) and [WEBHOOK_DELETE](#audit-actions).

| 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](/http-api/webhooks/#webhook-types) |

#### Emoji change fields

Recorded by [EMOJI_CREATE](#audit-actions), [EMOJI_UPDATE](#audit-actions) and [EMOJI_DELETE](#audit-actions).

| 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

Recorded by [STICKER_CREATE](#audit-actions), [STICKER_UPDATE](#audit-actions) and [STICKER_DELETE](#audit-actions).

| 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

A reduced [webhook object](/http-api/webhooks/#webhook-object) without the token, application ID and creator, and with `avatar_hash` in place of `avatar`.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the webhook |
| type | integer | The [webhook type](/http-api/webhooks/#webhook-types) |
| 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

<RouteHeader method="GET" path="/v1/guilds/{guild_id}/audit-logs" bot />

Returns one page of audit history as a [guild audit log response](#guild-audit-log-response-object) object, newest first. You need `VIEW_AUDIT_LOG`.

### 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](#audit-actions) |

Two or more [MESSAGE_DELETE](#audit-actions) entries in a row by the same user in the same channel are replaced by one [MESSAGE_BULK_DELETE](#audit-actions) 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](/http-api/threads/#client-capability) gets no entries about threads, forum channels or media channels, and filtering by actions 110 to 112 returns 400.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild audit log response](#guild-audit-log-response-object) object | The page was returned |
| 400 | [error response](/http-api/#error-response) | `CANNOT_SPECIFY_BOTH_BEFORE_AND_AFTER` when both cursors are sent, or a filter value is invalid |
| 403 | [error response](/http-api/#error-response) | You lack `VIEW_AUDIT_LOG` |
| 404 | [error response](/http-api/#error-response) | The guild does not exist |

The rate limit is 20 requests per 10 seconds, on the `guild:audit_logs::guild_id` bucket.