Audit logs

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:

1
{
2
  "id": "evt_01JCXP9K2H5RTQZ8Y3W6N4F0DA",
3
  "event_type": "api_key.created",
4
  "timestamp": "2026-05-21T17:32:01.412Z",
5
  "actor": {
6
    "type": "user",
7
    "id": "user_abc123",
8
    "ip_address": "203.0.113.42",
9
    "user_agent": "Mozilla/5.0 ..."
10
  },
11
  "target": {
12
    "type": "api_key",
13
    "id": "apk_xyz789"
14
  },
15
  "changes": {
16
    "name": "production-server",
17
    "scopes": ["conversations:write"]
18
  },
19
  "request_id": "req_01JCXP8Z9M2K7VBQ3D5N6T0HEX"
20
}

Event taxonomy

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:

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

Response:

1
{
2
  "data": [
3
    {
4
      "id": "evt_01JCXP9K2H5RTQZ8Y3W6N4F0DA",
5
      "event_type": "api_key.created",
6
      "timestamp": "2026-05-21T17:32:01.412Z",
7
      "..."
8
    }
9
  ],
10
  "next_cursor": "evt_01JCXP8Z9M2K7VBQ3D5N6T0HEX"
11
}

Pagination

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

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

Query parameters

Converting to NDJSON

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

1
curl -s "https://api.phonic.ai/v1/audit_logs?from=$FROM&to=$TO" \
2
  -H "Authorization: Bearer $PHONIC_API_KEY" \
3
  | 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 your workspace’s conversation retention mode. A workspace using zero retention for conversation content still retains its 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>:

1
HTTP/1.1 200 OK
2
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 and conversation.ended webhooks. These fire as conversations end and provide a low-latency event stream that complements the audit log.