VIEW_AUDIT_LOG permission and can be fetched by apps using the GET /guilds/{guild.id}/audit-logs endpoint, or seen by users in the guild’s Server Settings. All audit log entries are stored for 45 days.
When an app is performing an eligible action using the APIs, it 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.
Example Partial Integration Object
Audit Log Entry Object
Each audit log entry represents a single administrative action (or event), indicated byaction_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.
Apps 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 1-512 URL-encoded UTF-8 characters. Reasons are visible to users in the client and to apps when fetching audit log entries with the API.
Audit Log Entry Structure
Audit Log Events
The table below lists audit log events and values (theaction_type field) that your app 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 object.
You should assume that your app may run into any field for the changed object, though none are guaranteed to be present. In most cases only a subset of the object’s fields will be in the
changes array.
* Object has exception(s) to available keys. See the exceptions section below for details.
Optional Audit Entry Info
Audit Log Change Object
Many audit log events include achanges 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.If
new_value is not present in the change object while old_value is, it indicates that the property has been reset or set to null. If old_value isn’t included, it indicated that the property was previously null.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.Get Guild Audit Log
GET/guilds/{guild.id}/audit-logs
Returns an audit log object for the guild. Requires the VIEW_AUDIT_LOG permission.
The returned list of audit log entries is ordered based on whether you use before or after. When using before, the list is ordered by the audit log entry ID descending (newer entries first). If after is used, the list is reversed and appears in ascending order (older entries first). Omitting both before and after defaults to before the current timestamp and will show the most recent entries in descending order by ID, the opposite can be achieved using after=0 (showing oldest entries).