# Audit Logs

Every action performed in your Workspace is recorded automatically, including role changes, agent edits, content uploads, and deployments. Audit logs give administrators a chronological, filterable record for compliance reviews, security investigations, and change tracking.

Open **Workspace > Audit Logs** to view the log. Access is limited to the Workspace Admin role.

{% hint style="info" %}
Role-based access control (workspace, application, and agent-level roles) is covered in the [Users & Roles](/administration/users-and-roles.md) page.
{% endhint %}

### How Audit Logs Works

Audit logs turn raw Workspace activity into a record you can investigate, monitor, and prove. Four capabilities make this possible:

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-clipboard-list">:clipboard-list:</i></h4><h4>Automatic Recording</h4></td><td>Every administrative action in Workspace is captured the moment it happens, with no configuration required</td></tr><tr><td><h4><i class="fa-magnifying-glass">:magnifying-glass:</i></h4><h4>Targeted Investigations</h4></td><td>Combine user, category, date, and text filters to surface the exact events you need</td></tr><tr><td><h4><i class="fa-bell">:bell:</i></h4><h4>Proactive Notifications</h4></td><td>Selected administrators receive an email for every recorded event, delivered immediately</td></tr><tr><td><h4><i class="fa-file-csv">:file-csv:</i></h4><h4>Compliance Export</h4></td><td>Download the filtered view as a CSV file for archives or auditor requests</td></tr></tbody></table>

### What Events Get Tracked

Events are grouped into broad categories by the type of action they represent. Expand any one below to see some example events for each category:

<details open>

<summary><strong>Access Control</strong></summary>

User and group management actions that change who can access Workspace or what they can do.

* User logged in or out
* User invited or removed
* Workspace role changed (Viewer / Editor / Admin)
* User group created, modified, or deleted

</details>

<details>

<summary><strong>Content</strong></summary>

Changes to agents-related content.

* Workflow created, edited, or removed

</details>

<details>

<summary><strong>Agent Settings</strong></summary>

Configuration changes made to an agent in Designer.

* Agent settings updated
* Created or restored a backup for an agent
* Enabled or disabled monitoring for an agent

</details>

<details>

<summary><strong>Agent Deployments</strong></summary>

Deployment lifecycle events for agents across channels.

* Deployment created, updated, or deleted

</details>

<details>

<summary><strong>Workspace Settings</strong></summary>

Workspace-level configuration changes.

* Login settings updated (SSO, MFA)
* Data retention updated
* Audit log retention changed

</details>

<details>

<summary><strong>Workspace Management</strong></summary>

Higher-level Workspace administration actions.

* Agent created or deleted

</details>

### Searching and Filtering

Searching and filtering scope the log down to the events you care about. You can search for events by their description and filter by category or user. A date range can be layered on top of either to restrict results to a specific time window.

{% columns %}
{% column %}

#### <i class="fa-magnifying-glass">:magnifying-glass:</i> Search

Look up events by a keyword in their **Description**. Useful when you remember a fragment (an agent name, a file name, an email) but not the user or date.

<div data-with-frame="true"><figure><img src="/files/nOPcdwnfKsHcGY7fpzkc" alt="" width="250"><figcaption></figcaption></figure></div>
{% endcolumn %}

{% column %}

#### <i class="fa-filter">:filter:</i> Filters

Scope the log by **Category** to isolate one class of activity, or by **User name** to focus on a single actor. The two filters compose.

<div data-with-frame="true"><figure><img src="/files/JlBk2ZcuSazoDAhCZIK0" alt="" width="104"><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

### Log Retention

Audit log retention controls how far back the log goes, with a maximum of 3 months. Older entries are purged automatically once the window closes. Lowering the retention window does not delete older entries instantly. The purge runs on a schedule, so out-of-window entries may remain visible briefly before they are removed.

{% hint style="info" %}
This setting applies only to the audit logs. The broader platform data retention is covered in the [Data Privacy & Handling](/security/data-privacy-and-handling.md#data-retention) page.
{% endhint %}

### Email Notifications

Notifications keep a designated administrator in the loop without requiring them to open Workspace. The selected user receives an email for every audit event, sent immediately as it is recorded.&#x20;

Only one recipient can be configured at a time. A shared inbox or mail filter is the best fit when more people need visibility.

{% stepper %}
{% step %}

#### Start a New Subscription

Select **Email Notifications** in the top-right of the audit log view.
{% endstep %}

{% step %}

#### Pick the Recipient

Select the user who should receive notifications. Only users with access to Workspace appear in the list.
{% endstep %}

{% step %}

#### Confirm the Recipient

Close the panel. The recipient starts receiving emails for events recorded from that point onward.
{% endstep %}
{% endstepper %}

### Exporting to CSV

Export the current view as a CSV file for offline analysis, archiving, or sharing with stakeholders who do not have Workspace access. The export respects every filter applied to the log, so you can scope the file to a specific category, user, or date range before downloading.

To export, apply the filters you want and click the **Download** button.

Each row covers one audit event and contains:

* The columns present in the Audit Logs table
* The exact action performed
* The related deployment, agent, or Workspace ID when applicable

### Best Practices

* **Match retention to your compliance program:** Pick the longest window your policy allows; 3 months suits most organizations
* **Tighten Admin access first:** Anyone with the Admin role can read the log and change recipients, so audit your Admin roster before treating the log as authoritative
* **Export before reducing retention:** A shorter window will purge older entries, with no recovery option
* **Use category filters for compliance reports:** Filter to Access Control or Workspace Settings and export to CSV when preparing evidence for an audit

{% hint style="success" %}
You now have a full audit trail of Workspace activity, with filters, notifications, and CSV export to support your compliance program.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/security/audit-logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.