API reference

Audit log

Read an organization's audit log.

See Audit log for every recorded action.

`GET /v1/orgs/:orgId/audit`

One page of the audit log, newest first. Filter by action (an action or a category), actor or target. The first page also returns retentionDays.

Auth: user access token or platform agent key · Scope: audit:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Default	Notes
`cursor`	`string`	No		up to 4,096 characters
`action`	`string`	No		matches `^[a-z_]{1,32}(\.[a-z_]{1,32})?$`
`actor`	`string`	No		1–512 characters
`target`	`string`	No		matches `^[a-z_]{1,32}:[^\s]{1,512}$`
`limit`	`integer`	No	`50`	1–100; coerced from a string

Response 200

{
  events: {
    eventId: string
    orgId: string
    action: string
    actor: {
      type: "user" | "device" | "key" | "system"
      id: string
      label?: string
    }
    target: {
      type: string
      id: string
      label?: string
    }
    metadata?: {
      [key: string]: unknown
    }
    ip?: string
    userAgent?: string
    createdAt: number
  }[]
  cursor: null | string
  retentionDays?: number
}

Errors

Status	Message
`400`	Invalid cursor