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

# View Audit Trail

> Query, filter, and export the Essal Guard audit log to track all actions across the platform.

Every API request and user action across all six Essal apps is recorded in the **Guard audit log**. The log is immutable, tamper-evident, and retained according to your workspace's configured retention period (default: 90 days for standard plans, up to 7 years for enterprise).

## Querying the Audit Log

```bash theme={null}
GET /v1/guard/audit-logs?limit=25&sort=timestamp:desc
```

```json theme={null}
{
  "data": [
    {
      "id": "evt_01HXYZEVT9",
      "timestamp": "2026-07-10T15:23:44Z",
      "actor": { "type": "user", "id": "usr_01HXYZ1234", "email": "jane.doe@example.com" },
      "action": "office.document.deleted",
      "resource": { "type": "office.document", "id": "doc_01HXYZ9999" },
      "outcome": "success",
      "ip_address": "203.0.113.45",
      "user_agent": "Mozilla/5.0 ..."
    }
  ],
  "meta": { "total": 14832, "page": 1, "per_page": 25 }
}
```

## Filter Parameters

| Parameter       | Type     | Description                                    |
| --------------- | -------- | ---------------------------------------------- |
| `actor_id`      | string   | Filter by user or service account ID           |
| `action`        | string   | Filter by action type (e.g. `sales.deal.won`)  |
| `resource_type` | string   | Filter by entity type (e.g. `office.document`) |
| `resource_id`   | string   | Filter by specific entity ID                   |
| `outcome`       | enum     | `success`, `failure`, `denied`                 |
| `from`          | ISO 8601 | Start of time range                            |
| `to`            | ISO 8601 | End of time range                              |
| `ip_address`    | string   | Filter by source IP                            |

Example — find all failed login attempts in the last 24 hours:

```bash theme={null}
GET /v1/guard/audit-logs?action=access.user.login&outcome=failure&from=2026-07-09T00:00:00Z&to=2026-07-10T00:00:00Z
```

## Exporting Audit Logs

Export audit logs to a file for compliance reporting:

```bash theme={null}
POST /v1/guard/audit-logs/export
{
  "format": "csv",
  "filters": {
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-07-31T23:59:59Z"
  }
}
```

The export job runs asynchronously. A download URL is available in the `guard.audit.exported` webhook event or via polling `GET /v1/guard/exports/{job_id}`.

<Note>
  Audit log exports are available in `csv`, `json`, and `ndjson` formats. SIEM integrations should use `ndjson` for streaming-compatible output.
</Note>

## Retention Policy

Configure how long your workspace retains audit entries:

```bash theme={null}
PATCH /v1/guard/settings
{ "audit_retention_days": 365 }
```

Entries older than the retention period are automatically purged. Purge events are themselves logged and cannot be disabled.