Report CLI & sync

Everything renders from a local SQLite file — no server, no account.

stepcost report

stepcost report <db>                 # account summary across all traces
stepcost report <db> --trace <id>    # one trace's cost tree (per-node tokens + $)
stepcost report <db> --top 10        # top-N most expensive traces
stepcost report <db> --multiplier 30 # scale waste $ estimates (e.g. day → month)
stepcost report <db> --json          # machine-readable (incl. the span tree)

<db> accepts a plain path or a sqlite:///path URL.

Summary anatomy

By feature / by customer / by kind — dollar rollups over your business dimensions.
Top traces — the most expensive runs, for drill-down with --trace.
Waste signals — heuristics with estimated $ leaks: missing_cache (repeated large uncached prefixes; accounts for the cache-write premium and never flags traffic that already reads/writes cache), retry_loop (the same step ran 4+ times in one trace), oversized_context (input growing monotonically — full history re-sent), and model_oversized (frontier model producing tiny outputs). Flags, not prescriptions.
Unpriced spans — models with real tokens but no price-table entry. Loud on purpose: a silent $0 undercounts your total.
Provider reconciliation — appears automatically once you've run stepcost sync (below).

stepcost sync — the two-sided ledger

Pulls what your provider says it will bill (their organization cost APIs) into the same database, per day per model:

export ANTHROPIC_ADMIN_KEY=sk-ant-admin01-...   # Console → Settings → Organization → Admin keys
stepcost sync anthropic <db> --days 7

export OPENAI_ADMIN_KEY=...                     # platform.openai.com → Settings → Organization
stepcost sync openai <db> --days 7

The next stepcost report gains a reconciliation section:

Provider reconciliation (SDK-observed vs provider-billed):
  anthropic  2026-07-08   SDK $0.0190   billed $0.0190   drift 0.2%   coverage 100%
  2% gate (worst day): 0.23% — PASS ✅

Drift — |SDK − billed| / billed, per provider-day. This is StepCost's pricing accuracy, audited against the invoice continuously.
Coverage — SDK ÷ billed. Below 100% means spend the SDK never saw: uninstrumented call sites, scripts, or teammates' experiments. No SDK can see this alone — it's the provider ledger that exposes it.

Admin keys are a different key type from regular API keys (Anthropic: sk-ant-admin01-…, organization accounts only). Provider cost data appears with a delay — typically minutes, but new organizations can lag longer. Re-syncs are idempotent per provider-day.

Reading the trace view

stepcost report ~/.stepcost/my-app.db --trace 47b3783e
trace support-bot                           12,480 tok  $0.0152
├─ agent_step: plan                            1,380 tok  $0.0003
│  └─ llm gpt-4o-mini                          1,380 tok  $0.0003
└─ agent_step: execute                         4,100 tok  $0.0148
   └─ llm gpt-4o                               4,100 tok  $0.0148

Each node shows subtree tokens and dollars; the most expensive step is where to look first. --json emits the same tree machine-readably for your own tooling.

← Integrations Concepts & pricing →