---
title: Audit Logs
path: reference/audit
status: published
---

# Audit Reference

Endpoint reference for audit log queries and exports. For the guide, see [Audit Logs](../api-guides/audit-logs).

**Base path:** `/v1/audit/`

## GET /v1/audit/logs

Query the audit log.

Query parameters:

| Name | Type | Description |
|------|------|-------------|
| `from` | ISO 8601 | Start time |
| `to` | ISO 8601 | End time |
| `action` | string | One or comma-separated |
| `identity_id` | string | Exact match |
| `identity_type` | string | `user`, `service_account`, `group` |
| `path_prefix` | string | |
| `success` | boolean | |
| `source_ip` | string | Exact |
| `request_id` | string | Exact |
| `limit` | integer | Default 100, max 1000 |
| `cursor` | string | |

Actions:

`read`, `write`, `delete`, `list`, `rotate`, `policy_create`, `policy_update`, `policy_delete`, `policy_bind`, `policy_unbind`, `pki_issue`, `pki_sign`, `pki_revoke`, `pki_ca_create`, `dynamic_generate`, `dynamic_renew`, `dynamic_revoke`, `webhook_delivery`, `subscription_event`, `federation_sync`, `identity_sync`, `export_created`.

Response:

```json
{
  "logs": [
    {
      "id": "log_abc",
      "timestamp": "2026-04-23T...",
      "action": "read",
      "identity_type": "service_account",
      "identity_id": "sa:reporting",
      "secret_path": "integrations/salesforce/oauth",
      "source_ip": "10.0.1.50",
      "user_agent": "scaivault-python/1.0",
      "success": true,
      "duration_ms": 12,
      "request_id": "req_xyz",
      "extra_data": {}
    }
  ],
  "cursor": "...",
  "has_more": true
}
```

**Scope:** `audit:read`.

## GET /v1/audit/secrets/{path}

Secret-specific audit trail with 30-day summary.

**Scope:** `audit:read`.

## GET /v1/audit/identities/{identity_id}

Identity-specific audit trail with summary.

**Scope:** `audit:read`.

## GET /v1/audit/summary

Aggregate statistics.

Query: `from`, `to`.

Response:

```json
{
  "total_events": 125432,
  "successful_events": 124890,
  "failed_events": 542,
  "actions_breakdown": {"read": 98321, "write": 1432},
  "top_identities": [{"identity_id": "sa:reporting", "count": 35000}],
  "top_resources": [{"path": "integrations/salesforce/oauth", "count": 15000}]
}
```

**Scope:** `audit:read`.

## POST /v1/audit/export

Create an export job.

Body:

| Field | Description |
|-------|-------------|
| `from`, `to` | Time range |
| `format` | `jsonl` or `csv` |
| `filters` | Same as list filters |
| `destination.type` | `s3`, `gcs`, `azure_blob` |
| `destination.bucket` | |
| `destination.prefix` | |
| `destination.credentials_path` | ScaiVault secret path with upload creds |

Response `202 Accepted`: `export_id`, `status`, `estimated_records`.

**Scope:** `audit:export`.

## GET /v1/audit/exports

List exports.

**Scope:** `audit:export`.

## GET /v1/audit/exports/{id}

Export status and manifest.

Response:

```json
{
  "export_id": "exp_abc",
  "status": "completed",
  "record_count": 125432,
  "files": [
    {"key": "scaivault/2026-01/part-0001.jsonl", "size_bytes": 12345678}
  ],
  "completed_at": "2026-04-23T20:00:00Z"
}
```

## Related

- [Audit Logs Guide](../api-guides/audit-logs)
- [Error Codes](./error-codes)