> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesslabs.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

> Configure Headless event delivery, review the server's stored history, and diagnose channel and webhook delivery.

Moderation and server logs are stored per server and can be sent to one general channel or separate category and event destinations. Member reports use a separate destination and do not replace general logs.

## Destinations and route priority

Use `.logs set #channel` to set the general channel. Headless delivers logs exclusively through webhooks; when a send cannot be completed, it queues a retry and does not fall back to `channel.send`. Dashboard → Logs supports category and event destinations. Active delivery uses this priority: event-specific route → category route → general channel. If a specific destination is missing or no longer resolves to a text channel, delivery continues to the next configured route.

Current categories include moderation, messages, channels, roles, members, server, configuration, giveaways, minigames, security, and bot. `.logs off` removes the general channel and manual webhook URL. It does not erase history or separate routes configured in the dashboard.

## Setup, status, and diagnosis

Prefix commands use the server's configured prefix (`.` by default). The `/logs` group publishes `set`, `setup`, `status`, `diagnose`, and `test`; it does not provide `recent`, `search`, or `export` as slash subcommands.

`/logs setup channel:#mod-logs` saves the destination, creates or reuses the webhook, and sends a real test event. `.logs set #mod-logs` configures the destination and attempts webhook setup, but it is not the full slash setup. Use `.logs diagnose` to review Audit Log access, webhook, permissions, intents, delivery mode, and recent errors; `.logs test` sends a real test entry and distinguishes confirmed delivery, a queued retry, and unconfirmed delivery.

## Search and export history

`.logs recent [amount]` displays up to 20 entries (10 by default). Use a positive amount: the runtime does not normalize negative values. `.logs search <query>` performs a case-insensitive search across action, actor, target, reason, and ID, and displays up to 15 recent matches. `recent` and `search` require `Moderate Members`.

History is isolated per server. The default limit is 50,000 entries per server; `HEADLESS_LOG_HISTORY_LIMIT_PER_GUILD` can set it between 5,000 and 250,000. `.logs export` downloads the server's stored logs as JSON and requires `Administrator`; if the file exceeds 7 MB, the command will not attach it and points to the local data file instead.

## Permissions and privacy

Configuration, status, diagnosis, test, and export commands require `Administrator` from the user; history commands require `Moderate Members`. For prefix commands, compatible checks may accept Headless Fake Permissions; a virtual permission never replaces the bot's own permission. `/logs` publishes `Administrator` as its default permission and Headless checks it again locally.

To attribute events, the bot needs `View Audit Log`. It needs `Manage Webhooks` to create or repair webhooks. Log transport is webhook-only and has no `channel.send` fallback; the bot's message permissions do not turn a failed webhook delivery into a confirmed delivery. Diagnosis reports webhook permissions and whether member and message-content intents are available.

A webhook URL is an access credential. Do not post it, share it in screenshots, or store it in public channels. `.logs webhook clear` removes the manual URL; if it was exposed, also revoke or rotate the webhook in Discord.

## Member reports: separate destination

`.reportlogs [#channel]` configures where staff receive member-submitted reports and requires `Manage Server` (native or a compatible virtual permission). If no channel is supplied, the command saves the current channel as the destination. This report route does not change the general log channel or `.logs` category/event destinations; see [Moderation and reports](/docs/en/security/moderation.md) for the intake flow.

## Steps

**1. Choose the general destination**

Create or select a private staff channel and run `/logs setup #mod-logs` if you want Headless to test delivery during configuration.

**2. Add specific routes if needed**

In Dashboard → Logs, configure category or event destinations. Valid event routes take priority over category and general destinations.

**3. Check permissions and delivery**

Run `.logs diagnose` and `.logs test`; confirm that webhook delivery is reported as complete. If delivery is queued or fails, check `Manage Webhooks`, the selected route, and the error; there is no direct-send fallback.

**4. Restrict queries and exports**

Grant `Moderate Members` for history queries; reserve `Administrator` for configuration and export. Share JSON only with authorized staff.

## Commands by workflow

### Log destinations and webhook

```headless-command Syntax theme={null}
.logs set <channel>
```

```headless-command Example theme={null}
.logs set #mod-logs
```

```headless-command Syntax theme={null}
.logs webhook <url_or_clear>
```

```headless-command Example theme={null}
.logs webhook clear
```

```headless-command Syntax theme={null}
.logs off
```

```headless-command Example theme={null}
.logs off
```

### Slash setup and diagnostics

#### `/logs setup`

```headless-command Syntax theme={null}
/logs setup channel:<channel>
```

```headless-command Example theme={null}
/logs setup channel:#mod-logs
```

#### `.logs set`

```headless-command Syntax theme={null}
/logs set channel:<channel>
```

```headless-command Example theme={null}
/logs set channel:#mod-logs
```

#### `.logs status`

```headless-command Syntax theme={null}
/logs status
```

```headless-command Example theme={null}
/logs status
```

#### `.logs diagnose`

```headless-command Syntax theme={null}
/logs diagnose
```

```headless-command Example theme={null}
/logs diagnose
```

#### `.logs test`

```headless-command Syntax theme={null}
/logs test
```

```headless-command Example theme={null}
/logs test
```

### Query and export history

```headless-command Syntax theme={null}
.logs recent [amount=10]
```

```headless-command Example theme={null}
.logs recent 10
```

```headless-command Syntax theme={null}
.logs search <query>
```

```headless-command Example theme={null}
.logs search ban
```

```headless-command Syntax theme={null}
.logs export
```

```headless-command Example theme={null}
.logs export
```

### Member-report destination

```headless-command Syntax theme={null}
.reportlogs [channel]
```

```headless-command Example theme={null}
.reportlogs #private-reports
```

Also works: `.reportlogs`

> [!WARNING]
>
> An export can contain names, reasons, IDs, and moderation metadata. A webhook can publish as the bot: keep it secret and restrict access to exported files. Do not run `.logs recent` with a negative amount.

**Note:**

The event sent by `/logs setup` is real, but it is a `config_change` diagnostic entry, not a sanction or moderation event. `.logs test` also tests delivery by creating a log entry.

## Related pages

* [Moderation cases](/docs/en/moderation/cases.md)
* [Moderation and reports](/docs/en/security/moderation.md)
* [Headless permissions](/docs/en/permissions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.