Audit Logs Resource

When an administrative action is performed in a guild, an entry is added to its audit log. Viewing audit logs requires the VIEW_AUDIT_LOG permission and can be fetched using the Get Guild Audit Log endpoint. All audit log entries are stored for 45 days.

Audit Reason

When performing an eligible action using the API, users can pass an X-Audit-Log-Reason header to indicate why the action was taken. More information is in the audit log entry section.

Audit Log Object

Audit Log Structure

¹ Threads referenced in THREAD_CREATE and THREAD_UPDATE events are included in the threads map, since archived threads might not be kept in memory by clients.

Audit Log Entry Object

Each audit log entry represents a single administrative action (or event), indicated by action_type. Most entries contain one to many changes in the changes array that affected an entity in Discord—whether that's a user, channel, guild, emoji, or something else.

The information (and structure) of an entry's changes will be different depending on its type. For example, in MEMBER_ROLE_UPDATE events there is only one change: a member is either added or removed from a specific role. However, in CHANNEL_CREATE events there are many changes, including (but not limited to) the channel's name, type, and permission overwrites added. More details are in the change object section.

Users can specify why an administrative action is being taken by passing an X-Audit-Log-Reason request header, which will be stored as the audit log entry's reason field. The X-Audit-Log-Reason header supports up to 512 URL-encoded UTF-8 characters. Reasons are visible in the client and when fetching audit log entries with the API.

Audit Log Entry Structure

Audit Log Events

The table below lists audit log events and values (the action_type field) that you may receive.

The Object Changed column notes which object's values may be included in the entry. Though there are exceptions, possible keys in the changes array typically correspond to the object's fields. The descriptions and types for those fields can be found in the linked documentation for the object.

If no object is noted, there won't be a changes array in the entry, though other fields like the target_id still exist and many have fields in the options array.

¹ Object has exception(s) to available keys. See the exceptions section below for details.

Optional Audit Entry Info

¹ Due to technical limitations, this field is always serialized as a string, not an integer.

Audit Log Change Object

Many audit log events include a changes array in their entry object. The structure for the individual changes varies based on the event type and its changed objects, so apps shouldn't depend on a single pattern of handling audit log events.

Audit Log Change Structure

Some events don't follow the same pattern as other audit log events. Details about these exceptions are explained in the next section.

Audit Log Change Exceptions

For most objects, the change keys may be any field on the changed object. The following table details the exceptions to this pattern.

Partial Integration Object

Partial Integration Structure

Example Partial Integration

{
  "id": "1029376264039039006",
  "type": "discord",
  "name": "Good University",
  "account": {
    "id": "971811349262917662",
    "name": "Good University"
  },
  "application_id": "971811349262917662"
}

Partial Role Object

Partial Role Structure

Example Partial Role

{
  "name": "I am a role",
  "id": "584120723283509258"
}

Endpoints

Get Guild Audit Log

Returns an audit log object for the guild. Requires the VIEW_AUDIT_LOG permission.

Query String Params