How we compute spend

This page explains the spend figure on the dashboard (period total, daily series, by-model cut) and every aggregate spend number the platform serves with a link back to here.

What it is

Spend is what your providers charged for requests that passed through our gateway. We compute it per request from the token counts the provider reported in its own response, priced against a frozen, versioned rate list. It measures provider list cost, not your provider invoice, and it is computed, never inferred. We do not infer token counts or guess rates, and a request we cannot price is stored with a null cost.

How it is computed

All money is integer micro-USD, one millionth of a dollar. No floating-point number touches a price. For each request:

1. Find the (provider, model) row in the frozen price list pinned on the receipt as refPriceVersion, today rpl-2026-08-05. Rates are micro-USD per million tokens. A model absent from the list prices to null and raises price_list_mismatch internally. It is never inferred.
2. Resolve full-rate input. OpenAI reports cached_tokens inside prompt_tokens, so full-rate input is prompt_tokens - cached_tokens. Anthropic's input_tokens already excludes cache reads and writes, so it is used unchanged.
3. Sum four products in 128-bit integer arithmetic: full-rate input times inputPerMtok, cached tokens times cachedInputPerMtok, cache-write tokens times cacheWritePerMtok, completion tokens times outputPerMtok.
4. Floor-divide by 1,000,000, once, at the end, so per-component truncation cannot accumulate.

Reasoning tokens are not a separate term. Both providers report them inside completion tokens, so they price at the output rate exactly once. Detail a provider did not report contributes zero, because it is absent from that provider's invoice too. The receipt keeps the field null.

Worked example

An OpenAI gpt-4.1 request under rpl-2026-08-05: 5,211 prompt tokens of which 3,647 cached, and 804 completion tokens.

The sum is 11,383,500,000, which floor-divides to 11,383 micro-USD. The receipt renders 0.011383. The dashboard renders $0.01, rounded for display only, never for storage.

That integer is upserted additively into rollup_daily for the UTC day of the request start timestamp. Ingestion is idempotent on requestId, so a redelivered event never counts twice. Priced receipts also append to the workspace hash chain under recovea-chain-v1, which is the only recipe production writes. A second recipe, recovea-receipt-v1, is published with golden vectors, but nothing in the API writes or serves it. Both are SHA-256 over canonically encoded fields joined by U+001F. See receipts and ledger.

What it does not include

• Anything on your invoice that is not list price: discounts, committed-use, credits, free tiers, taxes.
• Rate dimensions outside the list schema: OpenAI long-context tiers above 272K input, Anthropic one-hour cache writes, regional uplifts, fast-mode SKUs. These price at the base rate, which under-measures and never over-charges.
• Traffic that did not pass through the gateway.
• Requests we could not price. They count as requests, hold a null cost, and add zero spend.
• Coalesced dedup followers, which made no provider call.
• Your Recovea subscription.

Limits and current status

• Budgets. Only workspace-scoped caps reach the gateway. The evaluator supports key and project scope, but the cap message the control plane pushes carries workspace scope only, so those caps are not enforced in path. Project-scoped spend reads as unknown, not zero, because receipts carry no project column.
• Alerts. The sweep runs once a minute. A fast burst can cross a threshold and reach a cap between ticks. Alerts warn on the way up. They are not an ordering guarantee.
• Counterfactual. Measured, never applied. No lever is activated in any deployed environment, and the shipped store returns no savings figure, so the surface stays empty.
• CPSO. Served at list price. The settled label flips when the calendar month ends, not because an invoice was reconciled. Period close runs only as a fixture-driven job with no schedule. Invoice reconciliation is planned, not wired.
• Score. The engine is not shipped. The store returns no factors, so no workspace has a score today.
• Spend and attribution drift. Project and tags are aggregated into rollup_cuts and rollup_tag_cuts but are not on the receipt row, so they cannot be re-derived from an export, and CPSO omits tag-based success rules for the same reason. Separately, the dashboard total and daily series read rollup_daily while the by-model cut reads receipts: same rows, two layers. The receipt commits in one transaction and the rollup in a second, so a rollup failure after the receipt lands leaves the redelivered event skipped as a duplicate and that spend missing from rollup_daily. Receipts are the record of truth, and no reconciliation job repairs such a gap today.

Where to check us

1. Export the period. Two routes serve the same chain. The session route, GET /platform/v1/ledger/export?period=YYYY-MM&format=jsonl, spells each row in camelCase: tokensIn, tokensOut, tokensCached, costMicroUsd, priceListVersion, previousHash and rowHash. The key-authed route, GET /v1/ledger/export, spells the same fields in snake_case. The ledger page carries the full field map for both.
2. Re-derive any row's cost with the four-term sum above at the rates for its pinned price list version. That rate table ships verbatim in our MIT-licensed CLI, in dist/prices.js of the recovea npm package — published as recovea@0.1.4, which pins rpl-2026-08-05, the same version this page describes. Run npm pack recovea and read the file. Two gaps remain: no endpoint serves the rate table over HTTP, and the package carries one table at a time, so a receipt pinned to a superseded version cannot be re-derived from the current release.
3. Sum costMicroUsd over the period and compare with the dashboard total. Unpriced requests contribute zero on both sides, so the two should agree to the micro-USD.
4. Re-derive the chain offline from the same export to confirm no row changed after the fact. The recipe is on the ledger page.

If your arithmetic and ours disagree, send us the request id. We publish the correction as a new row, never as an edit.