Audit Log

Guild audit logs let you inspect moderation and configuration actions recorded for a server. These logs are essential for tracking changes, ensuring accountability, and maintaining server security in Astral, which is compatible with Discord's API structure. Audit logs capture a wide range of events, including guild updates, channel creations or deletions, member kicks or bans, role updates, and more.

Endpoints

Astral provides endpoints to retrieve and interact with audit logs. The primary endpoint allows you to fetch audit log entries for a specific guild. Below is a comprehensive table of available endpoints:

Query Parameters

The GET endpoint supports several query parameters to filter and paginate results. These parameters help in efficiently retrieving relevant data without overwhelming the response.

Audit Log Objects and Fields

Audit log responses contain structured objects that describe each logged event. The main object is an AuditLog object, which includes an array of AuditLogEntry objects. Below are the detailed fields for these objects.

AuditLog Object

The top-level response object for the GET endpoint.

AuditLogEntry Object

Each entry in the audit log represents a single action.

Change Object (within AuditLogEntry)

Represents individual changes in an action.

Action Types

Audit logs track various events. Here's a table of common action types, based on Astral's compatibility with Discord:

JSON Examples

Below are examples of how to make requests and what responses might look like.

Request Example

For a GET request to fetch the last 50 audit logs filtered by a specific action type:

GET /guilds/1234567890/audit-logs?limit=50&action_type=22
Headers:
{
  "Authorization": "Bot YOUR_BOT_TOKEN"
}

Response Example

A successful response might look like this:

{
  "entries": [
    {
      "id": "9876543210",
      "action_type": 22,
      "target_id": "1122334455",
      "changes": [],
      "options": {
        "delete_member_days": "7",
        "count": 0
      },
      "user_id": "6677889900",
      "reason": "Violated community guidelines",
      "timestamp": "2023-10-01T12:00:00.000Z"
    }
  ],
  "webhooks": [],
  "users": [
    {
      "id": "6677889900",
      "username": "moderator_bot",
      "discriminator": "0001"
    }
  ],
  "integrations": []
}

Rate Limits

This endpoint is subject to Astral's standard rate limits to prevent abuse. Specifically:

• Global Limit: Up to 5 requests per 10 seconds per guild.
• Burst Limit: You may burst up to 10 requests, but sustained usage will be throttled.
• Headers: Responses include rate limit headers such as X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for precise tracking.

If you exceed these limits, you will receive a 429 Too Many Requests response. Implement exponential backoff in your client to handle retries gracefully.

Supplying an Audit Reason on Write Routes

Many moderation and management routes support the public header to provide a reason for actions, which will be recorded in the audit logs.

X-Audit-Log-Reason: Spam cleanup

Example

curl -X PUT \
  -H "Authorization: Bot $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Audit-Log-Reason: Spam" \
  -d '{"delete_message_days":1}' \
  https://astraof.com/api/v1/guilds/<GUILD_ID>/bans/<USER_ID>

Use this header whenever your bot performs actions like banning users, deleting channels, or updating roles to ensure traceability.

Best Practices

To effectively use audit logs in your Astral applications, consider the following guidelines:

• Efficient Querying: Use filters like user_id and action_type to minimize data transfer. Avoid fetching large unfiltered sets, as this can hit rate limits quickly.
• Pagination Handling: Always implement pagination to handle large logs. Start with a reasonable limit (e.g., 50) and use before or after for subsequent requests.
• Security and Privacy: Audit logs may contain sensitive information. Ensure that your application processes and stores this data securely, complying with relevant data protection regulations.
• Logging Actions: When your bot performs actions, always include an X-Audit-Log-Reason header to provide context, making it easier for server administrators to review logs.
• Error Handling: Check for permission errors (e.g., 403 Forbidden) if your bot lacks access. Also, handle 429 responses by implementing retry logic with increasing delays.
• Monitoring Changes: Use audit logs to monitor for unusual activity, such as mass deletions or role changes, and integrate with alerting systems if needed.
• Testing: In development, test your integration with a test guild to understand the response structures and avoid affecting live servers.

By following these practices, you can leverage audit logs to enhance moderation, improve accountability, and build more robust applications on Astral.