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

# Audit Log

> Immutable audit log for all agent actions. Query, filter, and export for compliance review.

# Audit Log

Anima maintains an append-only audit log of every authenticated API action performed by or on behalf of agents. The audit log is critical for compliance, incident response, and operational visibility.

## What Gets Logged

Every authenticated API call produces an audit entry with a semantic action name:

| Category | Example actions |
| - | - |
| **Agent** | `agent.create`, `agent.update`, `agent.delete`, `agent.rotate_key` |
| **Email** | `email.send`, `email.list`, `email.get`, `email.unsuppress` |
| **Messages** | `message.send_email`, `message.send_sms`, `message.search` |
| **Domains** | `domain.add`, `domain.verify`, `domain.delete` |
| **Phone/Voice** | `phone.provision`, `phone.send_sms`, `voice.create_call`, `voice.get_transcript` |
| **Vault** | `vault.create_credential`, `vault.get_totp`, `vault.share_credential` |
| **Identity** | `identity.get_did`, `identity.rotate_keys`, `identity.verify_credential` |
| **A2A** | `a2a.submit_task`, `a2a.get_task`, `a2a.cancel_task` |
| **Webhooks** | `webhook.create`, `webhook.update`, `webhook.test` |
| **Org/Auth** | `org.update`, `org.rotate_key`, API-key lifecycle |

Each entry records the actor (API key / user / agent / system), action, resource, result (`SUCCESS` / `FAILURE` / `DENIED`), IP address, user agent, and timestamp.

## Querying the Audit Log

Audit access is org-admin surface: use a **master key** (`mk_...`).

```
GET https://api.useanima.sh/v1/orgs/{orgId}/audit-logs
```

<Tabs items={["Node.js", "curl"]}>
  <Tab value="Node.js">
    ```ts theme={null}
    import { Anima } from "@anima-labs/sdk";

    const anima = new Anima({ apiKey: "mk_..." });

    // Query audit events (paginated)
    for await (const event of anima.audit.list(orgId, {
      action: "email.send",
      startDate: "2026-07-01T00:00:00Z",
      endDate: "2026-07-16T23:59:59Z",
      limit: 50,
    })) {
      console.log(`[${event.createdAt}] ${event.action}`);
      console.log(`  Actor: ${event.actorId} (${event.actorType})`);
      console.log(`  Resource: ${event.resourceType}/${event.resourceId} → ${event.result}`);
    }
    ```
  </Tab>

  <Tab value="curl">
    ```bash theme={null}
    curl "https://api.useanima.sh/v1/orgs/$ORG_ID/audit-logs?action=email.send&limit=50" \
      -H "Authorization: Bearer mk_..."
    ```
  </Tab>
</Tabs>

### Query Parameters

| Parameter | Type | Description |
| - | - | - |
| `actorId` | string | Filter by actor identifier |
| `actorType` | string | `API_KEY`, `USER`, `SYSTEM`, or `AGENT` |
| `action` | string | Filter by semantic action (e.g. `email.send`) |
| `resourceType` | string | Filter by resource type |
| `resourceId` | string | Filter by resource identifier |
| `result` | string | `SUCCESS`, `FAILURE`, or `DENIED` |
| `startDate` | string | ISO 8601 start time |
| `endDate` | string | ISO 8601 end time |
| `limit` | number | Max results per page (default 20, max 100) |
| `cursor` | string | Pagination cursor |

## Audit Event Structure

```json theme={null}
{
  "id": "cmb2xk1a90042abcd",
  "orgId": "cmb1x9k2l0000abcd",
  "actorType": "AGENT",
  "actorId": "cmb1xa3f50001abcd",
  "action": "email.send",
  "resourceType": "message",
  "resourceId": "cmb2xk0zz0041abcd",
  "result": "SUCCESS",
  "ipAddress": "10.0.1.42",
  "userAgent": "anima-node/0.5.1",
  "metadata": { "to": "ops@example.com", "subject": "Deploy complete" },
  "createdAt": "2026-07-15T14:32:01.234Z"
}
```

## Exporting Audit Logs

Export logs for compliance review as CSV or JSON:

```
POST https://api.useanima.sh/v1/orgs/{orgId}/audit-logs/export
```

<Tabs items={["Node.js", "curl"]}>
  <Tab value="Node.js">
    ```ts theme={null}
    const exportResult = await anima.audit.export(orgId, {
      format: "csv", // "csv" | "json"
      startDate: "2026-04-01T00:00:00Z",
      endDate: "2026-06-30T23:59:59Z",
    });

    console.log(`${exportResult.count} records`);
    await Bun.write("audit-q2-2026.csv", exportResult.data);
    ```
  </Tab>

  <Tab value="curl">
    ```bash theme={null}
    curl -X POST "https://api.useanima.sh/v1/orgs/$ORG_ID/audit-logs/export" \
      -H "Authorization: Bearer mk_..." \
      -H "Content-Type: application/json" \
      -d '{"format": "csv", "startDate": "2026-04-01T00:00:00Z"}'
    ```
  </Tab>
</Tabs>

The export returns the data inline in the response (`data`, `format`, `count`). Push it to your SIEM or archive from there — Anima does not currently stream directly to SIEM providers.

## Access Reviews

For SOC 2-style periodic access reviews, the audit API includes review tracking:

| Endpoint | Method | Description |
| - | - | - |
| `/v1/orgs/{orgId}/access-reviews` | POST | Start an access review (`QUARTERLY`, `AD_HOC`, `OFFBOARDING`) |
| `/v1/orgs/{orgId}/access-reviews` | GET | List access reviews |
| `/v1/orgs/{orgId}/access-reviews/{reviewId}/complete` | POST | Record findings + complete a review |

## API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/v1/orgs/{orgId}/audit-logs` | GET | Query audit events (filters above) |
| `/v1/orgs/{orgId}/audit-logs/{logId}` | GET | Get a single audit event |
| `/v1/orgs/{orgId}/audit-logs/export` | POST | Export as CSV/JSON |

## Next Steps

* [Anomaly Detection](/security/anomaly-detection) -- Detect unusual agent behavior
* [Compliance Reporting](/compliance/reporting) -- Generate compliance reports


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