---
title: "List audit logs"
method: GET
path: "/api/audit-logs"
tags: ["Audit Logs"]
---

# List audit logs

`GET /api/audit-logs`

Retrieves CADF-compliant audit log events with filtering, search, and
pagination via query parameters. Most filter dimensions accept either a
single value (singular parameter, e.g. `action`) or a JSON-encoded array
of values (plural parameter, e.g. `actions`); when both are supplied the
plural array takes precedence.

## Query parameters

- `page` integer
- `limit` integer
- `cursor` string
- `search` string
- `action` 'create' | 'read' | 'update' | 'delete' | 'authenticate' | 'authorize' | 'access' | 'enable' | 'disable' | 'start' | 'stop' | 'backup' | 'restore' | 'export' | 'import' — The CADF action performed.
- `actions` string
- `outcome` 'success' | 'failure' | 'pending' — The CADF outcome of the action.
- `outcomes` string
- `event_type` 'activity' | 'monitor' | 'control' — Classifies the audit event.
- `event_types` string
- `initiator_id` string
- `initiator_ids` string
- `initiator_type` 'user' | 'api_key' | 'system' | 'provider' | 'virtual_key' | 'team' | 'customer' | 'role' | 'permission' | 'guardrail' | 'mcp_client' | 'mcp_tool_group' | 'plugin' | 'config' | 'session' | 'inference' — The type of resource involved in an audit event (initiator or target).
- `initiator_types` string
- `target_id` string
- `target_ids` string
- `target_type` 'user' | 'api_key' | 'system' | 'provider' | 'virtual_key' | 'team' | 'customer' | 'role' | 'permission' | 'guardrail' | 'mcp_client' | 'mcp_tool_group' | 'plugin' | 'config' | 'session' | 'inference' — The type of resource involved in an audit event (initiator or target).
- `target_types` string
- `start_date` string
- `end_date` string
- `period` string
- `request_method` string
- `request_methods` string
- `request_path` string
- `request_paths` string
- `request_ip` string
- `request_ips` string
- `tags` string
- `sort_by` string
- `sort_order` 'asc' | 'desc'

## Response `200`

Successful response

- AuditLogsResult — A paginated result of audit logs.
  - `audit_logs` AuditEvent[], required — The list of audit events.
    - `id` string, required — Unique identifier for this event (UUID).
    - `typeURI` string, required — Event type URI (e.g., "http://schemas.bifrost.io/audit/api/v1").
    - `eventType` 'activity' | 'monitor' | 'control', required — Classifies the audit event.
    - `eventTime` string, date-time, required — When the event occurred (RFC 3339).
    - `action` 'create' | 'read' | 'update' | 'delete' | 'authenticate' | 'authorize' | 'access' | 'enable' | 'disable' | 'start' | 'stop' | 'backup' | 'restore' | 'export' | 'import', required — The CADF action performed.
    - `outcome` 'success' | 'failure' | 'pending', required — The CADF outcome of the action.
    - `initiator` AuditResource, required — A CADF resource (initiator, target, or observer).
      - `id` string, required — Unique identifier of the resource.
      - `typeURI` string, required — Resource type URI (e.g., "bifrost/user", "bifrost/api_key").
      - `name` string — Human-readable name of the resource.
      - `host` string — Hostname or IP address associated with the resource.
    - `target` AuditResource, required — A CADF resource (initiator, target, or observer).
      - `id` string, required — Unique identifier of the resource.
      - `typeURI` string, required — Resource type URI (e.g., "bifrost/user", "bifrost/api_key").
      - `name` string — Human-readable name of the resource.
      - `host` string — Hostname or IP address associated with the resource.
    - `observer` AuditResource, required — A CADF resource (initiator, target, or observer).
      - `id` string, required — Unique identifier of the resource.
      - `typeURI` string, required — Resource type URI (e.g., "bifrost/user", "bifrost/api_key").
      - `name` string — Human-readable name of the resource.
      - `host` string — Hostname or IP address associated with the resource.
    - `reason` AuditReason — The CADF reason for an outcome (especially for failures).
      - `reasonCode` string — Machine-readable code (e.g., "401", "FORBIDDEN").
      - `reasonType` string — Category of reason (e.g., "HTTP", "policy").
      - `message` string — Human-readable description.
    - `attachments` AuditAttachment[]
      - `name` string, required — Identifies the attachment.
      - `contentType` string, required — MIME type of the content.
      - `content` string, required — Attachment data (typically a JSON string).
    - `tags` string[] — Searchable labels for categorization.
    - `requestMethod` string — HTTP method (GET, POST, etc.).
    - `requestPath` string — HTTP request path.
    - `requestIP` string — Client IP address.
    - `userAgent` string — HTTP User-Agent header.
    - `duration` integer — Request duration in milliseconds.
    - `signature` string, required — HMAC-SHA256 signature for tamper detection.
    - `createdAt` string, date-time, required — When the record was created in the database.
  - `total` integer, required — Total count of events matching the filter.
  - `page` integer, required — Current page number.
  - `limit` integer, required — Page size.
  - `total_pages` integer, required — Total number of pages.
  - `has_more` boolean, required — Whether there are more results.
  - `next_cursor` string — Opaque cursor for the next page (cursor-based pagination).

## Other responses

- `400` — Bad request
- `500` — Internal server error

---

[API](https://skmtc.net/getbifrost/apis/bifrost-api.md) · [All operations](https://skmtc.net/getbifrost/apis/bifrost-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbifrost/bifrost-api/versions/f8cab88f64ea/schema)