StepCost documentation

FinOps for LLM agents: a priced, typed cost graph for every agent run — by step, by feature, by customer — reconciled against what your provider actually bills.

What StepCost is

Your provider bill tells you the total. Your observability tool tells you cost per request. Neither can answer the question that matters for a product: which step of which agent, serving which feature and which customer, is burning the money?

StepCost is an open-source Python SDK that treats agent cost as a first-class typed graph:

trace  support-bot / customer=acme                     $0.0152
├─ agent_step: plan                                    $0.0003
│  └─ llm_generation gpt-4o-mini                       $0.0003
├─ agent_step: retrieve
│  └─ embedding text-embedding-3-small                 $0.0002
└─ agent_step: execute
   └─ llm_generation gpt-4o                            $0.0148

The three guarantees

Invoice-grade pricing. Cache reads at 0.1x, 5-minute cache writes at 1.25x, 1-hour writes at 2x, reasoning tokens split from output — priced the way OpenAI (Chat Completions, Responses API, embeddings) and Anthropic actually bill. Verified on live Anthropic invoices — a 160-call run matched to the microdollar ($0.401618 = $0.401618); July 2026. A versioned, immutable price table gives finance a point-in-time audit trail.
Never a silent $0. Unrecognized usage shapes raise instead of recording zero. Models missing from the price table warn at runtime and appear as "unpriced spans" in every report.
Doesn't lose data. Spans persist at trace and process exit (no manual flush), sink failures re-queue instead of dropping, and concurrent async agents keep correct parent/child attribution. <5 ms p99 span-emit overhead.

The two-sided ledger

The SDK sees why you spent (step, feature, customer). Your provider's billing API knows what you'll pay. stepcost sync pulls the provider side into the same local database, and every report shows drift (does StepCost match the invoice?) and coverage (how much of the bill did instrumented code account for?). Each side audits the other's blind spot.

Privacy & deployment

Metadata-only by default: token counts, models, and your business dimensions — never prompt or response content. Fully offline: local SQLite, no account, no cloud. MIT licensed.

Quickstart →