audit-log

list

list audit log records on a site, auto-paginating through the server's cursor pagination until exhausted or --limit is hit.

synopsis — owlette audit-log list --site <siteId> [--kind <csv>] [--actor <actor>] [--since <when>] [--until <when>] [--limit <n>] [--cursor <token>] [--page-size <n>]

important filter caveats:

• the server only supports single-kind exact-match on kind. when you pass exactly one kind via --kind foo, the cli pushes the filter to the server. when you pass a CSV (--kind foo,bar), the cli falls back to client-side filtering after each page — the server still returns every kind and the cli drops the rest.
• --until is always client-side — there is no server until parameter. for very wide windows, prefer narrowing with --since to keep the server load reasonable.
• --since accepts both iso 8601 (2026-04-25T00:00:00Z) and relative durations like 24h, 7d, 30m, 5s. relative durations are converted to iso client-side before being sent.

cursor field name: the server returns canonical next_page_token plus deprecated nextPageToken. the cli prints it on the last line of human output as next cursor: <token> so you can resume.

# all events from the last 24 hours
owlette audit-log list --site site-1 --since 24h

# api-key usage in the last week, capped at 100 records
owlette audit-log list --site site-1 --kind api_key_used --since 7d --limit 100

# calls made by one api key
owlette audit-log list --site site-1 --actor apiKey:key_123 --since 24h

# multiple kinds — falls back to client-side filtering
owlette audit-log list --site site-1 --kind api_key_used,signed_url_issued --since 24h

# resume a paginated walk from a saved token
owlette audit-log list --site site-1 --cursor eyJsYXN0SWQiOi... --json | jq '.records | length'

backing endpoint: GET /api/sites/{siteId}/audit-log?kind=&actor=&since=&page_size=&page_token=

get

fetch one audit record by its recordHash and print the full payload — kind, actor, occurredAt, attributes — plus the hash chain (previousHash + hash) and the server's verification report (hashValid, linkageValid, isGenesis, predecessorPresent, reason). use this to verify a specific record or to follow the chain backwards.

synopsis — owlette audit-log get <recordHash> --site <siteId> [--json]

owlette audit-log get a1b2c3d4e5f6... --site site-1
owlette audit-log get a1b2c3d4e5f6... --site site-1 --json | jq '.verification'

a verification with ok: true means the record's content hashes to its claimed hash AND links correctly to its predecessor (or is the genesis record). if any field is false, the chain has been tampered with or the predecessor is missing.

backing endpoint: GET /api/sites/{siteId}/audit-log/{recordHash}

exit codes

• 0 — success
• 1 — generic error (network, api 5xx, unexpected response shape, missing --site, unparseable --since / --until)
• 2 — usage error (no token configured)

audit-log has no stub verbs and no exit-3 paths.

notes

• scope: site-scoped read. requires an api key with site=<id>:read (or broader).
• tier: A for both verbs.
• chain integrity: the verification report is computed server-side on every get. the cli does not re-hash records locally; for offline verification, fetch the full chain via --json and pipe to a tool that recomputes hashes.
• cli-side vs server-side filters: prefer single-kind --kind + --since for the cheapest queries — anything else streams more bytes than necessary. --limit short-circuits as soon as the cap is met regardless of where the filter ran.
• see overview for global flags and config precedence.