Skip to content
FiveCord Docs

Guild audit logs

An audit log entry records one change made to a guild and the account that made it. Only List guild audit logs and its Admin API counterpart read them.

A route marked Audit reason accepts the X-Audit-Log-Reason request header, listed with the other standard request headers. FiveCord reads the value verbatim and never percent-decodes it, so a caller that percent-encodes the reason stores and reads back the percent-encoded form.

FiveCord trims the value. A value that is blank before trimming, empty after it, or longer than 512 characters after it counts as no reason at all. None of those values fails the request, so a reason that misses the bound is dropped and the operation still succeeds.

The channel and message routes that write entries record the header as well: Modify channel, Delete or leave channel, Set channel permission overwrite, Delete channel permission overwrite, Delete message, Bulk delete messages, Pin message, and Unpin message.

Two operations use a reason from the request body when the header supplies none:

FiveCord never percent-decodes a body reason either. The operation writes the accepted reason onto its entry, returns it as the entry reason field, and sends it in the Guild Audit Log Entry Create Dispatch.

FiveCord resolves the reason again when it reads an entry. A MEMBER_BAN_ADD entry with a blank stored reason returns the ban reason from its change list, and a MEMBER_UPDATE entry with a blank stored reason returns the timeout reason stored with it, when it has one. The result is trimmed, and a blank result is omitted.

One page of audit history together with the accounts and webhooks it references. Only audit_log_entries is paginated.

FieldTypeDescription
audit_log_entries1array[guild audit log entry object]The page of entries this request returned
users2array[partial user object]The accounts the returned entries name
webhooks3array[audit log webhook object]The webhooks a returned webhook action targets

1 The page ordering is defined by the query parameters of the request that produced it

2 Deduplicated by user ID, and a referenced value that is not a snowflake names no account

3 One object for each distinct webhook that a returned webhook action targets and that still exists, so a deleted webhook resolves to no object

users has the actor of every returned entry and each account the entry references:

An account that can no longer be resolved is still returned, as the deleted-account representation with the username DeletedUser, the discriminator 0000, the global name Deleted User, a null avatar, a null avatar colour, and flags of 0.

One recorded guild change. An entry is immutable once written, except for a run of message deletion entries, which List guild audit logs can replace with a single consolidated entry.

FieldTypeDescription
idsnowflakeThe ID of the entry, whose snowflake timestamp is the time it was written
action_typeintegerAudit action value that identifies the recorded operation
user_id1snowflakeThe ID of the user that did the action
target_id2?stringThe ID of the affected entity
reason?3stringThe audit log reason recorded with the operation
options?4audit log options objectThe context fields this audit action records
changes?5array[audit log change object]The fields the mutation changed

1 Every entry has the acting user ID, and an entry produced by consolidation has the actor of the consolidated run

2 A decimal snowflake string for every action except INVITE_CREATE and INVITE_DELETE, where it is the invite code, and null for MESSAGE_BULK_DELETE

3 The field is omitted when no non-blank reason resolves as described under audit log reason, so an entry written by consolidation never has one

4 The field is omitted when the action recorded no option key that this registry publishes

5 The field is omitted when the action records no field change, so it is never returned as an empty array

{
"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}]
}

The Value column is the numeric action_type, which is also the value the action_type query filter accepts. Each description names what target_id identifies and which audit log options the action records. The overwrite options are id, type, channel_id, and role_name10. The invite options are max_age, max_uses, temporary, channel_id7, and inviter_id7.

ValueNameDescription
1GUILD_UPDATE1Guild settings or ownership were changed. target_id is the guild, and the action records no options
10CHANNEL_CREATEGuild channel was created. target_id is the channel, and the action records type
11CHANNEL_UPDATEGuild channel was changed. target_id is the channel, and the action records type
12CHANNEL_DELETEGuild channel was deleted. target_id is the channel, and the action records type
13CHANNEL_OVERWRITE_CREATEChannel permission overwrite was created. target_id is the role or member, and the action records the overwrite options
14CHANNEL_OVERWRITE_UPDATEChannel permission overwrite was changed. target_id is the role or member, and the action records the overwrite options
15CHANNEL_OVERWRITE_DELETEChannel permission overwrite was deleted. target_id is the role or member, and the action records the overwrite options
20MEMBER_KICK2Member was removed by a moderator. target_id is the user, and the action records no options
21MEMBER_PRUNE3Inactive members were pruned. target_id is nothing, and the action records no options
22MEMBER_BAN_ADDGuild ban was created or replaced. target_id is the user, and the action records delete_message_seconds4
23MEMBER_BAN_REMOVEGuild ban was removed. target_id is the user, and the action records no options
24MEMBER_UPDATEGuild member state was changed. target_id is the user, and the action records no options
25MEMBER_ROLE_UPDATEOne role was added to or removed from a member. target_id is the user, and the action records role_name5
26MEMBER_MOVE6Member voice session was moved to another channel. target_id is the user, and the action records channel_id and count
27MEMBER_DISCONNECT6Member voice session was disconnected. target_id is the user, and the action records channel_id and count
28BOT_ADDBot was added to the guild. target_id is the user, and the action records temporary
30ROLE_CREATERole was created. target_id is the role, and the action records no options
31ROLE_UPDATERole was changed. target_id is the role, and the action records role_name
32ROLE_DELETERole was deleted. target_id is the role, and the action records no options
40INVITE_CREATEInvite was created. target_id is the invite code, and the action records the invite options
41INVITE_UPDATE8Invite was changed. target_id is the invite code, and the action records no options
42INVITE_DELETEInvite was deleted. target_id is the invite code, and the action records the invite options
50WEBHOOK_CREATEWebhook was created. target_id is the webhook, and the action records channel_id7
51WEBHOOK_UPDATEWebhook was changed. target_id is the webhook, and the action records channel_id7
52WEBHOOK_DELETEWebhook was deleted. target_id is the webhook, and the action records channel_id7
60EMOJI_CREATEEmoji was created. target_id is the emoji, and the action records no options
61EMOJI_UPDATEEmoji was changed. target_id is the emoji, and the action records no options
62EMOJI_DELETEEmoji was deleted. target_id is the emoji, and the action records no options
72MESSAGE_DELETESingle message was deleted. target_id is the message, and the action records channel_id
73MESSAGE_BULK_DELETE9Several messages were deleted in one operation. target_id is nothing, and the action records channel_id and count
74MESSAGE_PINMessage was pinned. target_id is the message, and the action records channel_id and message_id
75MESSAGE_UNPINMessage was unpinned. target_id is the message, and the action records channel_id and message_id
90STICKER_CREATESticker was created. target_id is the sticker, and the action records no options
91STICKER_UPDATESticker was changed. target_id is the sticker, and the action records no options
92STICKER_DELETESticker was deleted. target_id is the sticker, and the action records no options

1 Recorded by Modify guild, by Modify guild custom invite URL, and by Transfer guild ownership, and target_id is the guild in every case

2 A kick entry is always recorded with no change list, so the removed membership state is not published through the entry

3 The value is defined by the wire contract and is accepted by the action_type filter, and no current guild operation records it

4 The option is recorded when the resolved message deletion window of the ban is positive. An older ban entry can have the deprecated delete_member_days option

5 Recorded when the role exists at the write. The role ID is the difference between the roles change values in the guild member change fields

6 count is always 1, and channel_id is the destination channel for a move and the vacated channel for a disconnect. A move into the channel the session already occupies records no entry

7 The option is recorded only when the recorded entity has that value, so an invite with no channel or no inviter records neither, and a webhook with no channel records no option at all

8 The filter accepts this value, and no current guild operation records this action

9 A bulk deletion entry is recorded either by a bulk message deletion operation or by the consolidation described under List guild audit logs

10 Recorded for an overwrite whose target is a role other than @everyone, when that role exists at the write

Every field is present only for the actions listed against it in the audit actions registry. Only the keys in this registry are published, and the response omits options entirely when an entry recorded none of them.

FieldTypeDescription
channel_idstringThe decimal ID of the channel the action concerns
count1numberThe number of entities the action affected
delete_member_days2stringThe whole days of the banned member’s messages the ban deleted
delete_message_seconds3numberThe seconds of the banned member’s messages the ban deleted
idstringThe decimal ID of the role or member an overwrite applies to
integration_type4numberThe type of the integration the entry names
message_idstringThe decimal ID of the single message the action concerns
members_removed4numberThe number of memberships the action removed
role_name5stringThe name of the role the action concerns, as it was when the entry was written
type6numberThe channel type, or the permission overwrite type
inviter_idstringThe decimal ID of the user that created the invite
max_agenumberThe configured invite lifetime in seconds
max_usesnumberThe configured maximum use count
temporarybooleanWhether the recorded entity is temporary
uses4numberThe invite use count recorded with the action

1 The value is the length of the consolidated run for MESSAGE_BULK_DELETE and is always 1 for the voice actions

2 Deprecated, and present only on a ban entry recorded before delete_message_seconds. Its value is the legacy delete_message_days body field of Create or replace guild ban, so a ban that sent only delete_message_seconds has "0"

3 Present when the resolved deletion window of Create or replace guild ban is positive, whichever body field set it

4 The field is defined by the wire contract and no current guild operation records it

5 Recorded by MEMBER_ROLE_UPDATE, ROLE_UPDATE, and an overwrite action whose target is a role other than @everyone

6 The value is a channel type for the channel actions and a permission overwrite type for the overwrite actions

One field a mutation changed, with the value on each side of the change.

FieldTypeDescription
key1stringThe name of the field that changed, drawn from the change fields of the entity the action targets
old_value?2audit log change valueThe value the field held before the mutation
new_value?2audit log change valueThe value the field holds after the mutation

1 A change whose key is ip is never published through this resource, and changes is omitted entirely when no other change remains

2 A creation has only new_value, a deletion has only old_value, and a modification has both, so a change object always has at least one of the two

A change value is a string, a JSON number, a boolean, null, an array of strings, an array of numbers, or an object with added and removed string arrays. The last shape comes only from the permissions_diff key of a role modification.

Each table below names the fields an action of that family can record.

Recorded by GUILD_UPDATE.

FieldTypeDescription
guild_id1stringThe decimal ID of the guild itself
namestringThe name the guild was given by this change (1-100 characters)
owner_idstringThe decimal ID of the guild owner
vanity_url_code?stringThe configured custom invite code, or null when the guild has none
icon_hash?stringThe guild icon hash, or null when the guild has no icon
banner_hash?stringThe guild banner hash, or null when the guild has no banner
banner_width?numberThe guild banner width in pixels, or null when the guild has no banner
banner_height?numberThe guild banner height in pixels, or null when the guild has no banner
splash_hash?stringThe guild splash hash, or null when the guild has no splash
splash_width?numberThe guild splash width in pixels, or null when the guild has no splash
splash_height?numberThe guild splash height in pixels, or null when the guild has no splash
splash_card_alignmentnumberThe splash card alignment recorded with the change
embed_splash_hash?stringThe guild embed splash hash, or null when the guild has no embed splash
embed_splash_width?numberThe guild embed splash width in pixels, or null when the guild has no embed splash
embed_splash_height?numberThe guild embed splash height in pixels, or null when the guild has no embed splash
features2array[string]The guild features held at this side of the change, in ascending order
verification_levelnumberThe verification level recorded with the change
mfa_levelnumberThe MFA level recorded with the change
nsfw_levelnumberThe NSFW level recorded with the change
nsfwbooleanWhether the guild is marked age restricted
content_warning_levelnumberThe guild content warning level recorded with the change
content_warning_text?stringThe configured content warning text, or null when the guild sets none
explicit_content_filternumberThe guild explicit content filter level recorded with the change
default_message_notificationsnumberThe default message notification level recorded with the change
system_channel_id?stringThe decimal ID of the configured system channel, or null when the guild sets none
system_channel_flagsnumberThe system channel flags mask recorded with the change
rules_channel_id3?stringThe decimal ID of the configured rules channel, or null when the guild sets none
afk_channel_id?stringThe decimal ID of the configured AFK voice channel, or null when the guild sets none
afk_timeoutnumberThe AFK timeout in seconds
disabled_operations3numberThe disabled guild operations mask recorded with the change
member_count3numberThe member count recorded with the mutation
message_history_cutoff?ISO8601 timestampThe configured message history cutoff, or null when the guild sets none

1 The field holds the same value on both sides of every guild action, so it never produces a change object

2 A change object appears only when a feature was added or removed

3 No current guild operation records the field

Modify guild records every field in this table except guild_id, owner_id, vanity_url_code, rules_channel_id, disabled_operations, and member_count. Transfer guild ownership records only owner_id, and Modify guild custom invite URL records only vanity_url_code.

Recorded by CHANNEL_CREATE, CHANNEL_UPDATE, and CHANNEL_DELETE.

FieldTypeDescription
channel_idstringThe decimal ID of the channel itself
typenumberThe channel type recorded with the change
name?stringThe name the channel was given by this change
topic?stringThe topic the channel was given by this change, or null when it has none
url1?stringThe destination URL of the channel, or null when it has none
parent_id?stringThe decimal ID of the parent category, or null when the channel sits at the top level
positionnumberThe position of the channel among its siblings
nsfw?booleanWhether the channel is marked age restricted, or null when it has no override
content_warning_levelnumberThe content warning level recorded with the change
content_warning_text?stringThe configured content warning text, or null when the channel sets none
rate_limit_per_usernumberThe slowmode interval in seconds
user_limit?numberThe configured voice occupancy limit
voice_connection_limit?numberThe configured per-user voice connection limit
bitrate?numberThe voice bitrate in bits per second
rtc_region?stringThe pinned voice region, or null when the channel is routed automatically
permission_overwrite_count2numberThe number of permission overwrites the channel has

1 Recorded only for a GUILD_LINK channel type

2 No current channel operation records the field. An individual overwrite mutation records its own permission overwrite entry

Changing permission_overwrites through Modify channel records overwrite entries and adds no change to the CHANNEL_UPDATE entry.

Recorded by the channel overwrite actions. Every value in this family is a string.

FieldTypeDescription
idstringThe decimal ID of the role or member the overwrite applies to
typestringThe decimal permission overwrite type
allowstringThe decimal permission mask the overwrite grants
denystringThe decimal permission mask the overwrite denies

Recorded by MEMBER_UPDATE and MEMBER_ROLE_UPDATE.

FieldTypeDescription
user_idstringThe decimal ID of the member itself
nick?stringThe nickname the member holds in this guild, or null when none is set
rolesarray[string]The assigned role IDs as decimal strings, in ascending string order
avatar_hash?stringThe guild avatar hash, or null when the member has no guild avatar
banner_hash?stringThe guild banner hash, or null when the member has no guild banner
bio?stringThe guild profile bio, or null when none is set
pronouns?stringThe guild profile pronouns, or null when none is set
accent_color?numberThe guild profile accent colour, or null when none is set
deafbooleanWhether a moderator has deafened the member
mutebooleanWhether a moderator has muted the member
communication_disabled_until?ISO8601 timestampThe time the communication restriction expires, or null when the member is not restricted
temporarybooleanWhether the membership is temporary

Recorded by MEMBER_MOVE and MEMBER_DISCONNECT.

FieldTypeDescription
channel_id1stringThe decimal ID of the voice channel the session occupied

1 A move records the previous channel as old_value and the destination as new_value, while a disconnect records only old_value

Recorded by MEMBER_BAN_ADD and MEMBER_BAN_REMOVE.

FieldTypeDescription
user_idstringThe decimal ID of the banned user
moderator_idstringThe decimal ID of the user that issued the ban
banned_atISO8601 timestampThe time the ban was issued
expires_at?ISO8601 timestampThe expiry of a temporary ban, or null for a permanent ban
reason1?stringThe stored ban reason

1 The body reason when the request sent one, and the X-Audit-Log-Reason value otherwise. The entry reason is the header when one was sent, so the two differ when a request sends both with different values

Recorded by ROLE_CREATE, ROLE_UPDATE, and ROLE_DELETE.

FieldTypeDescription
role_idstringThe decimal ID of the role itself
namestringThe name the role was given by this change (1-100 characters)
permissionsstringThe decimal permission mask the role grants
positionnumberThe position of the role in the guild hierarchy
hoist_position?numberThe separate hoisting position, or null when the role has none
colornumberThe colour recorded for the role
icon_hash?stringThe role icon hash, or null when the role has no icon
unicode_emoji?stringThe role Unicode emoji, or null when the role has none
hoistbooleanWhether the role is displayed separately
mentionablebooleanWhether the role is mentionable
permissions_diff1objectThe permission names this change added and removed

1 Recorded only by Modify guild role, and only when the mask changed. The value is an object with added and removed string arrays of permission names

permissions_diff arrives as new_value with no old_value, and the same change list still has the permissions change.

Modify guild role positions records one ROLE_UPDATE entry for each role that moved, with only the position change. FiveCord orders the roles other than @everyone by position descending, then by ID ascending, before and after the write. The largest set of roles that keep their relative order counts as unmoved, and where several sets qualify, the set whose roles come earliest in the new order is used. A request that only renumbers positions records no entry.

Modify role hoist positions and Reset role hoist positions apply the same rule to the member list order, with only the hoist_position change in each entry. That order is the hoisted roles other than @everyone, by hoist_position descending with position used when a role has no hoist position, then by ID ascending. A role that is not hoisted has an entry whenever its hoist_position changed.

Recorded by INVITE_CREATE and INVITE_DELETE.

FieldTypeDescription
codestringThe code that identifies the invite
channel_id?stringThe decimal ID of the channel the invite points at
guild_id?stringThe decimal ID of the guild the invite belongs to
inviter_id?stringThe decimal ID of the user that created the invite
usesnumberThe use count recorded with the change
max_usesnumberThe configured maximum use count
max_agenumberThe configured invite lifetime in seconds
temporarybooleanWhether accepting the invite grants a temporary membership
created_atISO8601 timestampThe time the invite was created

Recorded by WEBHOOK_CREATE, WEBHOOK_UPDATE, and WEBHOOK_DELETE.

FieldTypeDescription
idstringThe decimal ID of the webhook itself
guild_id?stringThe decimal ID of the guild the webhook belongs to
channel_id?stringThe decimal ID of the channel the webhook posts to
namestringThe name the webhook posts under (1-80 characters)
creator_id?stringThe decimal ID of the user that created the webhook
avatar_hash?stringThe webhook avatar hash, or null when no avatar is set
type1numberThe kind of webhook the change recorded

1 The value is 1 for an incoming webhook and 2 for a channel follower webhook

Recorded by EMOJI_CREATE, EMOJI_UPDATE, and EMOJI_DELETE.

FieldTypeDescription
emoji_idstringThe decimal ID of the emoji itself
namestringThe name the emoji was given by this change (2-32 characters)
animatedbooleanWhether the emoji is animated
creator_idstringThe decimal ID of the user that created the emoji

Recorded by STICKER_CREATE, STICKER_UPDATE, and STICKER_DELETE.

FieldTypeDescription
sticker_idstringThe decimal ID of the sticker itself
namestringThe name the sticker was given by this change (2-30 characters)
description?stringThe sticker description, or null when it has none
animatedbooleanWhether the sticker is animated
creator_idstringThe decimal ID of the user that created the sticker

A reduced webhook object. It omits the execution token, application ID, and creating user, and it names the avatar hash avatar_hash where the full object names it avatar.

FieldTypeDescription
idsnowflakeThe ID of the webhook
type1integerThe kind of webhook this record describes
guild_id?snowflakeThe ID of the guild containing the webhook
channel_id?snowflakeThe ID of the channel the webhook sends messages to
namestringThe name the webhook posts under
avatar_hash?stringThe avatar hash of the webhook, or null when no avatar is set

1 The value is 1 for an incoming webhook and 2 for a channel follower webhook

GET/v1/guilds/{guild_id}/audit-logsBot

Returns one page of guild audit history as a guild audit log response object. Requires VIEW_AUDIT_LOG in the target guild, and no MFA elevation applies.

A guild ID that names no guild returns 404 UNKNOWN_GUILD. A non-member of an existing guild returns 403 MISSING_PERMISSIONS, so guild existence is visible to any authenticated caller.

FieldTypeDescription
guild_idsnowflakeThe ID of the guild whose audit log is read
FieldTypeDescription
limit?1integerThe maximum number of entries to return (0-100, default 50)
before?2snowflakeThe cursor selecting entries older than this audit entry ID
after?2snowflakeThe cursor selecting entries newer than this audit entry ID
user_id?3snowflakeThe acting user ID the page is filtered by
action_type?3integerThe audit action value the page is filtered by

1 A negative value and a value above 100 are both rejected, and the accepted value 0 is processed as 1

2 The cursors are mutually exclusive, and supplying both returns 400 INVALID_FORM_BODY with CANNOT_SPECIFY_BOTH_BEFORE_AND_AFTER against before

3 Supplying either filter disables message deletion consolidation for the request, so a page filtered by actor or action returns the unconsolidated entries

The read is ordered from newest to oldest by entry ID. before selects entries below the cursor and after selects entries above it, both read in that same descending order. An after page therefore begins with the newest entry above the cursor.

Consolidated entries have new IDs but retain the position of the run they replace. Sort the page by ID if a strictly descending array is required.

A stored update entry that fails the no-change rule is skipped and does not count toward limit. A page holds fewer entries than limit only when the guild has no further matching entries in that direction.

StatusBodyCondition
200guild audit log response objectPage was returned
400error responseBoth cursors were supplied, or a filter value is invalid
4031error responseGuild is unavailable, or VIEW_AUDIT_LOG is absent
404error responseGuild does not exist and the request returns UNKNOWN_GUILD

1 The error code is MISSING_ACCESS for a guild with UNAVAILABLE_FOR_EVERYONE, or UNAVAILABLE_FOR_EVERYONE_BUT_STAFF without the instance staff flag, and MISSING_PERMISSIONS otherwise

A consolidated entry has a new ID, options.count equal to the number of replaced entries and no reason. It emits Guild Audit Log Entry Create to guild sessions holding VIEW_AUDIT_LOG.

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:audit_logs::guild_id bucket.