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

# Export Audit Logs for Compliance and Reporting

> Use the Idem Ledger compliance export endpoint to stream NDJSON audit records for any time window. Filter by HUMAN or AGENT activity for targeted reporting.

Every action taken in the Idem Ledger — whether by a human operator or an automated agent — is recorded in an immutable audit log. The compliance export endpoint lets you stream those records as newline-delimited JSON (NDJSON) for any time window you specify, making it straightforward to feed audit data into your SIEM, data warehouse, or compliance reporting pipeline.

## Export audit log

Send a `GET` request to `/api/v1/compliance/audit-export` with the required `from` and `to` query parameters. The response is a streaming NDJSON body: one JSON object per line, one line per audit record.

```bash theme={null}
curl "https://api.your-domain.com/api/v1/compliance/audit-export?from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z&type=ALL" \
  -H "Authorization: Bearer $IDEM_API_KEY"
```

## Query parameters

| Parameter | Required | Description                                                                                        |
| --------- | -------- | -------------------------------------------------------------------------------------------------- |
| `from`    | ✅ Yes    | Start of the export window. Must be a valid ISO-8601 timestamp (e.g., `2024-01-01T00:00:00Z`).     |
| `to`      | ✅ Yes    | End of the export window. Must be a valid ISO-8601 timestamp and must be after `from`.             |
| `type`    | No       | Filter by actor type. Accepted values: `HUMAN`, `AGENT`, or `ALL`. Defaults to `ALL` when omitted. |

Use `type=HUMAN` to export only records generated by human operators (console or direct API key usage), and `type=AGENT` to isolate automated agent activity. This is especially useful when your compliance team needs to audit human approvals separately from programmatic operations.

## NDJSON format

The response body is a stream of newline-delimited JSON. Each line is a self-contained JSON object representing one audit record. There is no wrapping array — process the stream line by line.

A single audit record looks like this:

```json theme={null}
{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"HUMAN","action":"POST_TRANSACTION","actorKeyId":"key_operator_01","occurredAt":"2024-01-15T10:30:00Z","payload":{}}
```

Key fields in each record:

| Field        | Description                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `id`         | Unique identifier for this audit record.                                                        |
| `type`       | Whether the action was taken by a `HUMAN` or `AGENT`.                                           |
| `action`     | The specific operation performed (e.g., `POST_TRANSACTION`, `REGISTER_SETTLEMENT`).             |
| `actorKeyId` | The identifier of the API key that performed the action.                                        |
| `occurredAt` | ISO-8601 timestamp of when the action occurred.                                                 |
| `payload`    | Additional structured context about the action, such as the transaction ID or affected account. |

## Processing NDJSON

Because each line is independent JSON, you can pipe the response directly into `jq` to filter or transform records on the fly:

```bash theme={null}
# Stream all HUMAN actions and extract just the action name and timestamp
curl -s "https://api.your-domain.com/api/v1/compliance/audit-export?from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z&type=HUMAN" \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  | jq -c '{action: .action, occurredAt: .occurredAt, actor: .actorKeyId}'
```

To write the raw stream to a file for offline processing:

```bash theme={null}
curl -s "https://api.your-domain.com/api/v1/compliance/audit-export?from=2024-01-01T00:00:00Z&to=2024-02-01T00:00:00Z" \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  > audit-jan-2024.ndjson
```

## Required scope

Your API key must have the **COMPLIANCE\_EXPORT** scope to call this endpoint. Requests from keys without this scope receive a `403 Forbidden` response. This scope should be granted only to keys used by compliance systems or authorized administrators, not to general-purpose service accounts.

<Note>
  For tenants with high transaction volumes, requesting large time windows in a single export can produce very large response streams. As a best practice, export in shorter windows — daily or weekly — rather than requesting months of data in one call. This keeps response sizes manageable, reduces the risk of a network interruption mid-stream, and makes it easier to parallelize ingestion into your downstream systems.
</Note>