Skip to content

Audit Logs

The canviq audit-logs command queries the API audit log. It requires the org:read scope on your API key and authentication (see Authentication). It also accepts the global --json/--quiet flags; see Scripting and CI.

Without --from, the API applies a 7-day default time window and returns only entries from the past 7 days.

Basic usage

# Last 100 entries from the past 7 days (default)
canviq audit-logs

# JSON output (useful for piping)
canviq audit-logs --json

Filters

Flag Description
--from <datetime> Start of the time range (ISO 8601, e.g. 2026-06-01 or 2026-06-01T00:00:00Z)
--to <datetime> End of the time range (ISO 8601)
--action <action> Filter by action string (e.g. tool.survey_create)
--key-id <uuid> Filter by API key ID
--limit <n> Maximum results (default 100, max 1000)
--cursor <cursor> Pagination cursor from a previous response
--json Output raw JSON
--quiet Suppress output except errors

Example: entries for a date range

canviq audit-logs \
  --from 2026-06-01 \
  --to 2026-06-30 \
  --json

Example: filter by actor key and action

canviq audit-logs \
  --key-id 01234567-89ab-cdef-0123-456789abcdef \
  --action tool.survey_create \
  --from 2026-06-01

Pagination

The API returns a next_cursor field when more results exist. Pass it with --cursor to fetch the next page.

# Page 1
canviq audit-logs --limit 100 --json > page1.json

# Page 2: use the cursor from page 1
CURSOR=$(jq -r '.next_cursor' page1.json)
canviq audit-logs --limit 100 --cursor "$CURSOR" --json > page2.json

In human-readable mode (TTY), the CLI prints the pagination hint automatically:

Next page: canviq audit-logs --cursor <cursor>

Shell loop: fetch all pages

#!/usr/bin/env bash
CURSOR=""
PAGE=0

while true; do
  FILE="audit-page-${PAGE}.json"
  FLAGS="--limit 1000 --json"
  if [ -n "$CURSOR" ]; then
    FLAGS="$FLAGS --cursor $CURSOR"
  fi

  # shellcheck disable=SC2086
  canviq audit-logs $FLAGS > "$FILE"

  NEXT=$(jq -r '.next_cursor // empty' "$FILE")
  if [ -z "$NEXT" ]; then
    echo "Done. $((PAGE + 1)) page(s) fetched."
    break
  fi

  CURSOR="$NEXT"
  PAGE=$((PAGE + 1))
done

Rate limits

The audit log endpoint allows 60 requests per hour. Exceeding this limit returns exit code 5. The CLI prints the Retry-After seconds when the header is present.

See Troubleshooting for how this command's error handling differs slightly from the survey/question/trigger groups: it maps 403 and 429 explicitly, but any other non-2xx response (including 401) falls back to a generic exit code 1 rather than exit code 3.