Guild audit logs¶

An audit log entry records one change made to a guild and the account that made it. Entries are written by the operations that change a guild and read with List guild audit logs.

The route is relative to https://tebhos.com/api/v1, requires authentication and accepts both user sessions and bot tokens. Error bodies follow Errors.

Audit log reason¶

TEBHOS does not read an audit-log reason from a request header. Two operations take a reason from their body and store it on the entry:

• Create guild ban uses reason.
• Modify guild member uses timeout_reason when it sets a timeout.

Every other entry has a null reason.

Guild audit log response object¶

A user in users has id, username, discriminator, global_name, avatar, avatar_color and flags. An account that no longer exists is returned with an empty username, discriminator "0000" and null avatar fields.

Guild audit log entry object¶

Entries expire 45 days after they are written.

{
  "id": "1501314428688998184",
  "action_type": 22,
  "user_id": "1489002177550843905",
  "target_id": "1489002177550843906",
  "reason": "Advertising",
  "options": {"tebhos_action": "MEMBER_BAN", "target_type": "member"},
  "changes": []
}

Audit log change object¶

TEBHOS records only the new side of a change; there is no old_value. Most actions record the entity's name. Modify guild records each of name, features, icon, banner, splash and embed_splash it changed; Modify guild role records name and color; a webhook creation also records channel_id; voice moves record channel_id and connection_id; server mute and deafen record mute and deaf.

Audit actions¶

The value is the numeric action_type, which is also what the action_type query parameter accepts. The last column shows whether a current TEBHOS operation writes the action.

TEBHOS-specific actions. Actions with no standard number are stored with action_type 0 and identified by options.tebhos_action:

Such entries can be read without an action_type filter. Filtering with action_type=0 returns them.

List guild audit logs¶

GET /guilds/{guild_id}/audit-logs

Returns one page of audit history as a guild audit log response object. Requires VIEW_AUDIT_LOG.

Rate limit: guild:audit_logs, 20 per 10 seconds per account and guild.

Query parameters¶

Entries are always returned newest first, with after too: an after page starts with the newest entry above the cursor. To walk backwards through history, pass the id of the last entry you received as before.

curl "https://tebhos.com/api/v1/guilds/1489002177550843904/audit-logs?limit=25&action_type=22" \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

The guild also receives a Guild Audit Log Entry Create event over the Gateway when most entries are written. Entries with action_type 0 are not dispatched.