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 |
GET /v1/orgs/:orgId/audit/export
Daily JSON Lines export of the audit log into one of the org's buckets (audit/<yyyy-mm-dd>.jsonl).
Auth: user access token or platform agent key · Scope: audit:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
export: {
bucketId: null | string
bucket: null | {
name: string
region: string
prefix: string
}
pendingDays: string[]
}
}Errors
| Status | Message |
|---|---|
404 | Organization not found |
PUT /v1/orgs/:orgId/audit/export
Turns the daily export on (bucketId: an active bucket of the org) or off (null). Owners and admins.
Auth: user access token or platform agent key · Scopes: audit:read, org:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
bucketId | string | Yes | 1–64 characters; can be null |
Response 200
{
export: {
bucketId: null | string
bucket: null | {
name: string
region: string
prefix: string
}
pendingDays: string[]
}
}Errors
| Status | Message |
|---|---|
400 | Choose an active bucket of this organization. |
404 | Organization not found |