Export API Usage

Four endpoints under /api/v2/export/* provide bulk CSV/JSON exports of the same aggregated data your dashboard views show — never raw event payloads. All four share the same contract:

• Auth: Authorization: Bearer <api-key> (same as every other /api/v2/* endpoint — see seed_dev.sql for a dev key, or mint your own via POST /api/v2/api-keys/self).
• Format: ?format=csv (default) or ?format=json.
• Pagination: ?cursor=<token>&limit=N (default limit=1000, max 5000). cursor is an opaque token — never construct or parse it yourself; pass back the exact next_cursor value from the previous response. next_cursor is null/absent once you've reached the last page.
• CSV shape: header row always present; a trailing # next_cursor: <token> comment line when there's a next page (omitted on the last page). Data rows above that line parse as a clean table with any standard CSV reader.
• JSON shape: {"items": [...], "next_cursor": "<token>" | null}.

Examples below assume the Quick Start setup from README.md — server on http://localhost:8080, API key from seed_dev.sql (rsk_dev_test_key_12345).

export RAI_API_KEY=rsk_dev_test_key_12345
export RAI_BASE_URL=http://localhost:8080

/api/v2/export/cost

Tool cost aggregated by (tool_name, unit) — the same rows GET /api/telemetry/tool-cost and the TokenCostPanel dashboard widget show.

# CSV (default)
curl -H "Authorization: Bearer $RAI_API_KEY" \
  "$RAI_BASE_URL/api/v2/export/cost"

# JSON, scoped to a project, custom page size
curl -H "Authorization: Bearer $RAI_API_KEY" \
  "$RAI_BASE_URL/api/v2/export/cost?format=json&project=my-project&limit=100"

CSV columns: tool_name, unit, amount, cost_usd, event_count.

/api/v2/export/audit

Governance audit trail — never raw payloads, only payload_hash (a sha256 hex digest). Filters: event_kind, work_item_ref, project_id.

curl -H "Authorization: Bearer $RAI_API_KEY" \
  "$RAI_BASE_URL/api/v2/export/audit?format=json&event_kind=gate_decision"

CSV columns: timestamp, gate_type, actor_member_id, work_item_ref, artifact_ref, decision, payload_hash.

/api/v2/export/metrics

Delivery KPIs — one row per card (cycle_time, deploy_frequency, change_failure_rate, rework_rate), same formulas as GET /api/v2/metrics. has_data=false upstream (no qualifying events yet) exports zero rows rather than fabricated zeroes.

curl -H "Authorization: Bearer $RAI_API_KEY" \
  "$RAI_BASE_URL/api/v2/export/metrics?format=json&start_date=2026-08-01&end_date=2026-08-15"

CSV columns: date, metric_name, value, unit.

/api/v2/export/adoption

Adoption usage paired with gate-decision quality — same snapshot as GET /api/v2/adoption. Quality columns are always present, even when the sample size is zero (first_pass_gate_success_rate/acceptance_rate are null, never a fabricated 0% or 100%).

curl -H "Authorization: Bearer $RAI_API_KEY" \
  "$RAI_BASE_URL/api/v2/export/adoption?format=csv"

CSV columns: date, total_members, active_members, period_days, first_pass_gate_success_rate, sample_size, acceptance_rate, hitl_sample_size.

Paginating a full export (any endpoint)

cursor=""
while :; do
  page=$(curl -s -H "Authorization: Bearer $RAI_API_KEY" \
    "$RAI_BASE_URL/api/v2/export/cost?format=json&limit=500${cursor:+&cursor=$cursor}")
  echo "$page" | jq -c '.items[]' >> cost-export.jsonl
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

No anonymous export

Every endpoint above requires a valid, authenticated API key — same verify_member dependency chain as GET /api/v2/metrics. An unauthenticated or invalid-key request returns 401. Any member with a resolved plan (community and up — including the team-plan license seed_dev.sql seeds) can call every export endpoint — there is no separate paid-tier gate on top of authentication, and no anonymous or "preview" export mode.