> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.phonic.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.phonic.ai/_mcp/server.

# Audit Logs

> Pull SIEM-ready audit logs covering identity, configuration, and data-handling events for your workspace.

Phonic emits structured audit logs for administrative and data-handling
actions in your workspace. The logs are designed for ingestion into SIEM
tools (Splunk, Datadog, Panther, etc.): stable field names, RFC3339
timestamps, one event per line when converted to NDJSON, no nested payload
blobs.

Audit logs are separate from API request logs. Routine API calls (creating
conversations, sending TTS) do not appear here; only actions that change
identity, configuration, or persisted data are recorded.

## Event schema

Every event has the same top-level shape:

```json
{
  "id": "evt_01JCXP9K2H5RTQZ8Y3W6N4F0DA",
  "event_type": "api_key.created",
  "timestamp": "2026-05-21T17:32:01.412Z",
  "actor": {
    "type": "user",
    "id": "user_abc123",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ..."
  },
  "target": {
    "type": "api_key",
    "id": "apk_xyz789"
  },
  "changes": {
    "name": "production-server",
    "scopes": ["conversations:write"]
  },
  "request_id": "req_01JCXP8Z9M2K7VBQ3D5N6T0HEX"
}
```

| Field              | Description                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| `id`               | Unique event ID. ULID, sortable by time.                                                            |
| `event_type`       | Stable string identifier. See taxonomy below.                                                       |
| `timestamp`        | RFC3339 UTC, millisecond precision.                                                                 |
| `actor`            | Who performed the action.                                                                           |
| `actor.type`       | One of `user`, `api_key`, `jwt`, `phonic_support`.                                                  |
| `actor.id`         | Opaque identifier. For `phonic_support`, a support ticket reference.                                |
| `actor.ip_address` | Source IP. Omitted for `phonic_support` actions.                                                    |
| `actor.user_agent` | Source user-agent string. Omitted when not applicable.                                              |
| `target`           | The resource affected. `{type, id}`.                                                                |
| `changes`          | Changed field names with new values. Sensitive fields (API key value, webhook secret) are redacted. |
| `request_id`       | The originating API request ID, when the event was triggered by an API call.                        |

## Event taxonomy

| Category              | Event types                                                                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Identity & access** | `api_key.created`, `api_key.deleted`, `api_key.rotated`, `member.invited`, `member.removed`, `role.granted`, `role.revoked`, `jwt_issuer.registered`, `jwt_issuer.updated`, `jwt_issuer.deleted` |
| **Configuration**     | `workspace.setting_changed`, `agent.created`, `agent.updated`, `agent.deleted`, `webhook.created`, `webhook.updated`, `webhook.deleted`                                                          |
| **Data handling**     | `data.export_requested`, `conversation.hard_deleted`, `user.data_deleted`, `retention_mode.changed`                                                                                              |

This taxonomy is stable. Phonic will add new event types over time but will
not rename or remove existing ones.

## Retrieving audit logs

Pull audit logs with `GET /v1/audit_logs`:

```http
GET /v1/audit_logs?from=2026-05-01T00:00:00Z&to=2026-05-21T00:00:00Z&limit=1000
Authorization: Bearer <PHONIC_API_KEY>
```

Response:

```json
{
  "data": [
    {
      "id": "evt_01JCXP9K2H5RTQZ8Y3W6N4F0DA",
      "event_type": "api_key.created",
      "timestamp": "2026-05-21T17:32:01.412Z",
      "..."
    }
  ],
  "next_cursor": "evt_01JCXP8Z9M2K7VBQ3D5N6T0HEX"
}
```

### Pagination

Pass the `next_cursor` value from each response as the `cursor` parameter on
the next request. Iteration ends when `next_cursor` is `null`.

```http
GET /v1/audit_logs?from=...&to=...&cursor=evt_01JCXP8Z9M2K7VBQ3D5N6T0HEX
```

### Query parameters

| Parameter    | Required | Description                                                           |
| ------------ | -------- | --------------------------------------------------------------------- |
| `from`       | yes      | Inclusive start, RFC3339.                                             |
| `to`         | yes      | Exclusive end, RFC3339. Maximum window: 30 days.                      |
| `event_type` | no       | Filter to one or more event types. Repeat the parameter for multiple. |
| `limit`      | no       | Max events per page. Default 100, max 1000.                           |
| `cursor`     | no       | Pagination cursor from a previous response.                           |

### Converting to NDJSON

Most SIEM ingestors expect newline-delimited JSON. Convert with `jq`:

```sh
curl -s "https://api.phonic.ai/v1/audit_logs?from=$FROM&to=$TO" \
  -H "Authorization: Bearer $PHONIC_API_KEY" \
  | jq -c '.data[]'
```

For incremental ingestion, persist the highest `id` seen and use it as the
`cursor` on the next pull.

## Authorization

Reading audit logs requires an API key with the **admin** role. Standard API
keys cannot list audit events. This prevents a compromised low-privilege
key from enumerating workspace activity.

The act of reading audit logs is itself audited (`audit_log.exported`) so you
can detect unusual access patterns.

## Retention

Audit logs are retained for **1 year** by default. Enterprise workspaces can
request longer retention (up to 7 years) for compliance with SOC 2 Type II,
HIPAA, or sector-specific frameworks. Contact your account team to change
your retention window.

Audit logs are **not** subject to an agent's
[conversation data retention policy](/docs/platform/retention). An agent
using zero data retention for conversation content still leaves a full audit
trail. These are compliance records, not customer content.

## Correlating audit events with API requests

Every Phonic API response includes an `X-Request-Id` header of the form
`req_<26-char ULID>`:

```http
HTTP/1.1 200 OK
X-Request-Id: req_01JCXP8Z9M2K7VBQ3D5N6T0HEX
```

When an audit event was triggered by an API call, the same value appears in
the event's `request_id` field. This lets you trace from a specific request
through to the resulting audit entry. When opening a support ticket,
including the `X-Request-Id` lets Phonic engineers triage faster.

If you supply your own `X-Request-Id` on a request, Phonic will echo it back
if it matches the expected format (`req_` prefix, 30 characters total);
otherwise a server-generated ID is used.

## Real-time escalation feed

The audit log is a pull-based, slower-moving administrative trail. For
real-time monitoring of conversation outcomes (transfers to human agents,
completions, errors), subscribe to the
[`conversation.transferred`](/docs/build/with-webhooks/post-call-webhooks/conversation-transferred) and
[`conversation.ended`](/docs/build/with-webhooks/post-call-webhooks/conversation-ended) webhooks. These
fire as conversations end and provide a low-latency event stream that
complements the audit log.