> ## 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.

# User history

> Headless records local name history and global avatar history from events it observes. It cannot recover changes from before the bot observed them.

## Observed history

`.names` shows names and nicknames recorded for a member in the current server. `.avatars` reads Headless's global avatar history. Only changes observed by Headless are included; neither view is a complete lifetime record or recovers earlier data.

### `.userhistory`

```headless-command Syntax theme={null}
.userhistory [user]
```

```headless-command Example theme={null}
.userhistory @Member
```

Also works: `.history 123456789012345678` · `.uh @Member`

### `/userhistory`

```headless-command Syntax theme={null}
/userhistory user:<user>
```

```headless-command Example theme={null}
/userhistory user:@Member
```

### `.names`

```headless-command Syntax theme={null}
.names [user_query]
```

```headless-command Example theme={null}
.names @Member
```

### `.avatars`

```headless-command Syntax theme={null}
.avatars [user_query]
```

```headless-command Example theme={null}
.avatars @Member
```

## Staff timeline

`.userhistory <user>` (aliases `.history` and `.uh`) resolves a mention, ID, or name. `/userhistory user:<member>` opens the slash version. The prefix command requires Manage Messages; the slash command declares that default permission and also checks staff access. The view shows account/join dates, risk score, cases, warnings, timeouts, jail, kicks, bans, roles, and recent activity, with controls to open cases, refresh, and copy the ID.

Headless-generated panel headings and controls are currently in English. Server names and previously stored event data or reasons keep their original text.

## Deletion and scope

`clearnames` clears name history in the current server; `clearhistory` clears that history and global avatar history. Both run immediately without a confirmation prompt; clearing another member's data requires staff permission and may create an audit entry.

### `.clearnames`

```headless-command Syntax theme={null}
.clearnames [user_query]
```

```headless-command Example theme={null}
.clearnames @Member
```

### `.clearhistory`

```headless-command Syntax theme={null}
.clearhistory [user_query]
```

```headless-command Example theme={null}
.clearhistory @Member
```

> [!WARNING]
>
> `.clearhistory` is destructive: it immediately removes both local names and global avatars. Verify the target and scope before running it; there is no confirmation prompt.

## Public summary

The public Insights endpoint is limited to aggregate seven-day metrics and a tracked-profile count; it does not publish individual timelines. Detailed data requires a Dashboard session and the applicable permission in that server.

## Steps

**1. Read without changing data**

Use names or avatars with the member you want to inspect.

**2. Check the scope**

Distinguish server-local name history from global avatar history.

**3. Clear only when appropriate**

Use clearnames to clear names only, or clearhistory to clear names and avatars. Both operations run immediately; verify the target before invoking them.

## User History scope

> **[Private staff timeline](/docs/en/moderation/user-tools.md)**
>
> The panel searches by mention, ID, or name and shows risk score, observed moderation events, and recent activity. Its controls open related cases, refresh the view, and copy the member ID.
>
> <ul>
>   <li>Resolve by mention, ID, or name</li>
>   <li>Risk score and observed moderation/activity events</li>
>   <li>The current version does not provide TXT export</li>
>   <li>The public summary does not expose individual timelines</li>
> </ul>

## Related pages

* [User tools](/docs/en/moderation/user-tools.md)
* [Logging](/docs/en/server/logging.md)


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