> ## 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, export, and integrate with SIEM systems.

# Audit Log

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

## What Gets Logged

Every API call, agent action, and system event produces an audit entry:

| Category     | Events                                                     |
| ------------ | ---------------------------------------------------------- |
| **Agent**    | Create, update, delete, suspend                            |
| **Email**    | Send, receive, forward, delete                             |
| **Cards**    | Create, authorize, decline, close                          |
| **Vault**    | Store, retrieve, rotate, delete secrets                    |
| **Wallet**   | Payment, budget change, approval request                   |
| **Identity** | DID creation, key rotation, credential issuance/revocation |
| **A2A**      | Task sent, received, completed, failed                     |
| **Auth**     | API key created, rotated, revoked; login attempts          |
| **Pod**      | Created, updated, deleted, bridge created                  |

## Querying the Audit Log

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

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

    // Query audit events
    const events = await anima.auditLog.query({
      agentId: "ag_8f3k2m9x1n4p7q6r",
      category: "email",
      action: "send",
      startTime: "2026-03-01T00:00:00Z",
      endTime: "2026-03-28T23:59:59Z",
      limit: 50,
    });

    for (const event of events.data) {
      console.log(`[${event.timestamp}] ${event.action}`);
      console.log(`  Actor: ${event.actorId} (${event.actorType})`);
      console.log(`  Resource: ${event.resourceType}/${event.resourceId}`);
      console.log(`  Details: ${JSON.stringify(event.metadata)}`);
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python theme={null}
    from anima import Anima

    anima = Anima(api_key="ak_...")

    events = anima.audit_log.query(
        agent_id="ag_8f3k2m9x1n4p7q6r",
        category="email",
        action="send",
        start_time="2026-03-01T00:00:00Z",
        end_time="2026-03-28T23:59:59Z",
        limit=50,
    )

    for event in events.data:
        print(f"[{event.timestamp}] {event.action}")
        print(f"  Actor: {event.actor_id} ({event.actor_type})")
        print(f"  Resource: {event.resource_type}/{event.resource_id}")
    ```
  </Tab>

  <Tab value="Go">
    ```go theme={null}
    import "github.com/anima-labs-ai/go"

    client := anima.NewClient("ak_...")

    events, err := client.AuditLog.Query(ctx, &anima.AuditLogQueryParams{
        AgentID:   "ag_8f3k2m9x1n4p7q6r",
        Category:  "email",
        Action:    "send",
        StartTime: "2026-03-01T00:00:00Z",
        EndTime:   "2026-03-28T23:59:59Z",
        Limit:     50,
    })
    ```
  </Tab>
</Tabs>

## Audit Event Structure

```json theme={null}
{
  "id": "evt_9x2m4k7p1n",
  "timestamp": "2026-03-15T14:32:01.234Z",
  "category": "email",
  "action": "send",
  "actorId": "ag_8f3k2m9x1n4p7q6r",
  "actorType": "agent",
  "resourceType": "message",
  "resourceId": "msg_abc123",
  "podId": "pod_prod",
  "metadata": {
    "to": "ops@example.com",
    "subject": "Deploy complete",
    "decision": "delivered",
    "ruleEvaluations": [
      { "rule": "per_minute_rate_limit", "result": "pass" },
      { "rule": "daily_send_quota", "result": "pass" },
      { "rule": "domain_allowlist", "result": "pass" }
    ]
  },
  "ipAddress": "10.0.1.42",
  "userAgent": "anima-sdk-node/1.5.0",
  "immutableHash": "sha256:a1b2c3d4..."
}
```

## Exporting Audit Logs

Export logs for compliance review or SIEM integration:

<Tabs items={["Node.js", "Python"]}>
  <Tab value="Node.js">
    ```ts theme={null}
    // Export to JSON
    const exportJob = await anima.auditLog.export({
      format: "json",           // "json" | "csv" | "parquet"
      startTime: "2026-01-01T00:00:00Z",
      endTime: "2026-03-31T23:59:59Z",
      destination: "s3://my-bucket/audit-logs/q1-2026.json",
    });

    console.log(`Export job: ${exportJob.id}, Status: ${exportJob.status}`);

    // Stream to a SIEM (Splunk, Datadog, etc.)
    await anima.auditLog.configureSiemStream({
      provider: "datadog",
      apiKey: "dd_...",
      site: "datadoghq.com",
      tags: ["env:production", "service:anima"],
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python theme={null}
    export_job = anima.audit_log.export(
        format="json",
        start_time="2026-01-01T00:00:00Z",
        end_time="2026-03-31T23:59:59Z",
        destination="s3://my-bucket/audit-logs/q1-2026.json",
    )

    print(f"Export job: {export_job.id}, Status: {export_job.status}")
    ```
  </Tab>
</Tabs>

## API Reference

| Endpoint                                                | Description              |
| ------------------------------------------------------- | ------------------------ |
| `GET https://api.useanima.sh/api/audit-log/events`      | Query audit events       |
| `GET https://api.useanima.sh/api/audit-log/events/{id}` | Get a single audit event |
| `POST https://api.useanima.sh/api/audit-log/export`     | Start an export job      |
| `GET https://api.useanima.sh/api/audit-log/export/{id}` | Check export job status  |
| `POST https://api.useanima.sh/api/audit-log/siem`       | Configure SIEM streaming |
| `GET https://api.useanima.sh/api/audit-log/siem`        | Get SIEM configuration   |

### Query Parameters

| Parameter   | Type   | Description                                                  |
| ----------- | ------ | ------------------------------------------------------------ |
| `agentId`   | string | Filter by agent                                              |
| `podId`     | string | Filter by pod                                                |
| `category`  | string | Filter by category (e.g., `email`, `phone`, `vault`, `auth`) |
| `action`    | string | Filter by specific action                                    |
| `startTime` | string | ISO 8601 start time                                          |
| `endTime`   | string | ISO 8601 end time                                            |
| `limit`     | number | Max results (default 50, max 1000)                           |
| `cursor`    | string | Pagination cursor                                            |

## Configuration

| Variable                      | Default   | Description                            |
| ----------------------------- | --------- | -------------------------------------- |
| `ANIMA_AUDIT_RETENTION_DAYS`  | `365`     | How long to retain audit events        |
| `ANIMA_AUDIT_HASH_ALGORITHM`  | `sha256`  | Hash algorithm for immutability proofs |
| `ANIMA_AUDIT_SIEM_BATCH_SIZE` | `100`     | Batch size for SIEM streaming          |
| `ANIMA_AUDIT_EXPORT_MAX_ROWS` | `1000000` | Maximum rows per export job            |

## Next Steps

* [Anomaly Detection](/security/anomaly-detection) -- Detect unusual agent behavior
* [SOC 2 Controls](/compliance/soc2-controls) -- Map audit events to SOC 2 controls
* [Compliance Reporting](/compliance/reporting) -- Generate compliance reports