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

# Audit Logs

> API reference for Essal Guard audit logs — query, filter, export, and configure retention.

## List Audit Log Entries

`GET /v1/guard/audit-logs`

**Query Parameters**

| Parameter       | Type     | Description                       |
| --------------- | -------- | --------------------------------- |
| `actor_id`      | string   | Filter by user or service account |
| `action`        | string   | e.g. `office.document.deleted`    |
| `resource_type` | string   | e.g. `office.document`            |
| `resource_id`   | string   | Specific entity ID                |
| `outcome`       | enum     | `success`, `failure`, `denied`    |
| `from`          | ISO 8601 | Start of time range               |
| `to`            | ISO 8601 | End of time range                 |
| `limit`         | integer  | Results per page (max: 100)       |
| `cursor`        | string   | Pagination cursor                 |

**Response**

```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"
    }
  ],
  "meta": { "total": 14832, "next_cursor": "evt_01HXYZEVT8", "has_more": true }
}
```

***

## Export Audit Logs

`POST /v1/guard/audit-logs/export`

```json theme={null}
{
  "format": "csv",
  "filters": {
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-07-31T23:59:59Z"
  }
}
```

**Response** — `202 Accepted`

```json theme={null}
{ "job_id": "exp_01HXYZEXP9", "status": "pending" }
```

Poll `GET /v1/guard/exports/{job_id}` for the download URL.

***

## Get Retention Settings

`GET /v1/guard/settings`

***

## Update Retention Settings

`PATCH /v1/guard/settings`

```json theme={null}
{ "audit_retention_days": 365 }
```