Skip to content

Reading the Spend screen: provenance, rates and attribution

Read every figure on the Spend screen correctly: who counted it, whether it is real or notional money, which rate priced it, and how to export it per key.

14 min readLast reviewed October 19, 2026Verified against gateway chart 0.10.0

What you’ll have at the end

By the end of this guide you can take any number off the Spend screen and say who counted it, what kind of money it is, what rate priced it and what it was measured against. You can also pull the same figures per key or per person over the management API and know which fields to trust.

Before you begin

  • A Nautili team with traffic through the gateway this calendar month. The Spend screen reports one UTC month at a time.
  • Access to the Spend screen. The Vendor usage sub-page is visible to team admins only.
  • For the export step, a management key with the usage:read scope. Issue one on API keys with kind management. A key issued with no scopes holds all four scopes.
  • Your gateway host. The management API is served by a self-hosted gateway with MGMT_API_ENABLED=true (plus AUTH_TOKEN and GOVERNANCE_ISSUED_KEYS=true, which a governed install already sets). The DevZero-hosted Shared Gateway does not serve the management API yet; on it, read per-key spend from the API keys table.

Every figure on the Spend screen answers four questions. Who counted it. What kind of money is it. What rate priced it. What was it measured against. Each step below takes one of those questions off a part of the screen.

Step 1: Read the two arms

Open Spend. Below the period total and the daily chart sit two sections, each with its own colour, its own total and its own footed counts.

ArmManaged by DevZeroWhat it holdsRequests forwarded on credentials DevZero holds for youWho can count itThe gateway, and the provider's own ledger once it has been read
ArmYour own provider keysWhat it holdsRequests forwarded on credentials you suppliedWho can count itThe gateway only. DevZero never sees that invoice

Each arm foots four counts under its total: Requests, Input tokens, Output tokens and Cache-read tokens. The chart above uses the same two colours, so the chart is the legend.

The screen carries no seat column. Subscription seats (prepaid logins to AI coding tools) are reported on the Seats screen as capacity: active seats, requests, tokens and an API-equivalent value. That value is what the traffic would have cost on a metered API. It is informational, never dollars saved, because a flat seat fee moves nothing when traffic drops.

Step 2: Read the provenance chip

Next to each arm's title sits a chip that names who counted the figure. The two values come from the SpendProvenance enum on the wire.

ChipMeaning
Provider-attestedThe upstream's own ledger says this. Only possible on the managed arm, and only once the usage sweep has read that period. The section then shows a "Provider figure read" timestamp.
Gateway-reportedMeasured by your gateway as requests passed through. The only value the Your own provider keys arm can ever show.

These are not two categories of spend. They are two ways of knowing what was spent, and the same arm can change chip between periods: managed spend reads Gateway-reported until the provider has been read for that month, then flips to Provider-attested.

Two consequences follow, and the screen states both rather than leaving you to notice the arithmetic.

  • The daily bars are gateway-measured on both arms, including the managed one. The provider's figure is monthly-grained and cannot be split across days without inventing a distribution. So the managed arm's bars show the shape of its spend while its section total may show the provider's number.
  • Invoicing still uses the gateway's own measurement. The managed arm's tooltip says this outright: the attested figure is authoritative for the spend, but your invoice for the period may not match it exactly while DevZero establishes how far the two normally differ.

The footer under the arms explains the remaining gap: tokens served from cache never reached a provider, so nothing charged for them. It states the cache-read token count and its share of everything your requests moved.

Step 3: Read the kind of money and the rate

Two separate questions hide behind every dollar sign: whether an invoice stands behind it, and which price table produced it.

What kind of money. The regime is decided by the shape of the credential the request arrived on.

RegimeMeteredCredentialPer-token API keys, yours or DevZero'sThe figureReal invoice dollars
RegimeSubscriptionCredentialPrepaid seats on OAuth-shaped credentialsThe figureNotional. Catalog-priced, no invoice behind it
RegimeUnclassifiedCredentialNo resolvable credentialThe figureEvidence of neither. Reported separately

Unclassified traffic is never folded into either side. Folding it into metered would pad the real-dollar figure; folding it into subscription would inflate the notional one.

What rate. A rate is contracted, list or absent.

BasisMeaning
ContractedYour negotiated per-model price, which you supplied. The only input for a billable figure
List priceThe public price table. Directional, labelled as such, never billable
UnpricedNo rate resolved. Reported as unpriced, never as zero

List prices come from the backend's model catalog, the same catalog GET /api/v1/models is served from. A list-price figure is systematically high for any discounted team, in the direction that flatters the vendor. Wherever the product cannot resolve a contracted rate, it names the models it fell back on rather than mixing the two.

Unpriceable and free are different answers. A model whose rate could not be found is named, not priced at zero, and a request the upstream reported nothing for is counted and never priced.

Step 4: Read savings and efficiency as the docs define them

Savings reporting was retired together with prompt compression, and the dashboard renders no savings figure today. The one savings-shaped number that remains is API-equivalent value on Seats: what subscription-seat traffic would have billed on the metered API, labelled informational and never presented as savings.

Efficiency is a waste diagnostic. The Efficiency screen scores people and teams from two directly measured token pillars, retry waste and prompt repetition waste, as 100 x (1 - wasted tokens / total tokens). The score is absolute, never relative to peers. Absolute waste is shown in dollars for metered traffic only.

Read the coverage line before any score. It states what share of the team's tokens are identity-attributed. The uncovered share is unmeasured, not merely unlabelled, and a person carrying only an attribution tag has no efficiency score at all rather than a score of zero. If coverage is thin, the Link identities link on that page is the fix.

Step 5: Find who spent it

Attribution resolves from three inputs merged in a fixed order.

Order1 (lowest)SourceA workload attribution rule you configuredWins overNothing
Order2SourceThe owner of the issued key the request usedWins overThe rule
Order3 (highest)SourceThe tags the caller sent on the requestWins overBoth

The tags are the X-Dz-User, X-Dz-Team, X-Dz-Project, X-Dz-Env and X-Dz-Labels headers. They are free strings. Nothing validates them, so checkout, Checkout and check-out are three projects. A rule can never override a tag the caller sent.

Three screens roll this up.

  • People lists each person your telemetry knows, linked to a DevZero user or not. An unlinked vendor account is a full row with spend. The Linking tab is where identities get linked, and a person key changes shape when that happens, so link early.
  • Teams rolls spend up by team. A managed team joins telemetry through its immutable attribution key; an observed team is a tag value with no record behind it and so has no owner, colour or monthly figure. A managed team's monthly figure enforces nothing. Only a guardrail budget refuses a request.
  • Services lists the backend services calling the gateway with their spend, tokens and error rate. A registered but silent service returns zeros; an unknown one is a not-found error.

Per key, the API keys table shows each runtime key's spend over the last 30 days (the Spend (30d) column) beside the guardrail that governs it. A management key carries no inference traffic, so its row shows n/a in the custody, guardrail, spend and credit-limit columns rather than a zero that looks like "no usage yet".

The API keys table showing per-key spend and the governing guardrail for each runtime key

Step 6: Export the same numbers

The management API returns one principal's spend against its governing guardrail. Two routes, one response shape.

curl -sS "https://<your-gateway-host>/api/v1/keys/<KEY_ID>/usage" \
-H "Authorization: Bearer $NAUTILI_KEY"

The gateway resolves the key's governing policy and returns its accounting window. Revoked keys stay readable, because usage is a historical audit record.

For a person instead of a key, use the generic route with principal_kind and principal_ref.

curl -sS "https://<your-gateway-host>/api/v1/usage?principal_kind=identity&principal_ref=<USER_ID>" \
-H "Authorization: Bearer $NAUTILI_KEY"

principal_ref is a DevZero user id for identity and a key id for key. Both routes need the usage:read scope.

Verify

A successful read returns 200 with the Usage object. Trimmed to the fields that matter:

{
"policy_id": "6d1f0c2e-4b7a-4c1e-9a6b-2f3e8c9d0a11",
"source": "managed",
"active": true,
"counter_scope": "principal",
"limit_micro_usd": 50000000,
"window_start": "2026-10-01T00:00:00Z",
"reset": "2026-11-01T00:00:00Z",
"principal_spent_micro_usd": 12345678,
"principal_spent_complete": true,
"remaining_micro_usd": 37654322,
"queried_at": "2026-10-09T14:02:11Z"
}

Money is integer micro-USD, so 50000000 is $50.00. source names the credential source of the governing policy. Every value that does not apply is a literal null, never 0, because 0 here would read as "spent nothing". Check principal_spent_complete before treating principal_spent_micro_usd as a total: historical rows can predate a column it depends on, and the flag says whether the sum is whole. A lifetime window reports window_unbounded: true and a null reset.

On the dashboard the same figure appears as the key's spend cell on API keys and, for the team, as Total this period on Spend. The budget line under that total shows a percentage only when the team's guardrail resets monthly, because only a monthly ceiling spans the same calendar month the page reports. A daily, weekly or lifetime limit is stated as "Daily limit $X. This page reports a calendar month, so the total above is not measured against it." with no percentage.

Options

principal_kind=key

Select one runtime key. principal_ref is required.

GET /api/v1/usage?principal_kind=key&principal_ref=<KEY_ID>

Pass: 200 with the Usage object above. Deny: an unknown, cross-team or management key returns one byte-identical 404:

{"error":{"code":"not_found","message":"key not found"}}

principal_kind=identity

Select one linked DevZero user. An unknown id resolves like any unbound identity (the team default policy, or source: "none") rather than erroring.

GET /api/v1/usage?principal_kind=identity&principal_ref=<USER_ID>

Pass: 200. Deny: a read before the operator has set the principal-key coverage marker returns 409 with an actionable message. Key reads work immediately; identity reads need that fleet-wide rollout first.

The unattributed bucket

An empty principal_ref with principal_kind=identity selects the unattributed bucket.

GET /api/v1/usage?principal_kind=identity&principal_ref=

Because an empty ref is a real answer, the query contract is strict. An unknown or duplicated parameter returns 400:

{"error":{"code":"invalid_request","message":"unknown query parameter \"principal_reff\""}}

GET /api/v1/keys/{id}/usage accepts no query parameters at all and returns 400 with "this route accepts no query parameters" if given any.

Reading checklist

Ask these five questions before quoting any number from the screen.

  1. Who counted it? Read the chip. Gateway-reported is the gateway's count; Provider-attested is the ledger's. Only the managed arm can ever be attested.
  2. What kind of money? Metered is real dollars. Subscription is catalog-priced notional. Unclassified is neither. Seat figures are capacity, never savings.
  3. What rate? Contracted is billable. List price is directional and high for a discounted team. Unpriced is a named gap, not a zero.
  4. Measured against what? There is no savings figure to measure against; API-equivalent value on Seats is informational, and the efficiency score is measured waste, not a rating.
  5. Does the window match? The screen is one UTC calendar month. A daily or weekly guardrail does not compare to it, and a chart spanning an instrumentation or pricing boundary reads a change in counting as a change in cost.

Troubleshooting

Symptom or error"Could not load your billing summary"CauseThe read failedWhat to doNot a period with no spend. Retry; do not record a zero.
Symptom or error"No requests in this period"CauseNo request reached a provider this UTC monthWhat to doNothing was billed. Figures appear once traffic flows through your gateway.
Symptom or errorProvenance chip changed from Gateway-reported to Provider-attestedCauseThe usage sweep read the provider's ledger for that monthWhat to doExpected. The total may move; the daily bars stay gateway-measured.
Symptom or errorManaged total does not match your invoiceCauseInvoicing uses the gateway measurement, the attested total is the provider'sWhat to doExpected while reconciliation drift is characterised. Quote the invoice for billing, the attested figure for spend.
Symptom or errorDaily bars do not sum to the section totalCauseBars are gateway-measured, total is provider-attestedWhat to doRead the bars for shape and the total for amount.
Symptom or errorNotional figure differs from what you paidCauseSubscription spend is catalog-priced with no invoice behind itWhat to doDo not reconcile it against a bill. Read seat figures as capacity.
Symptom or errorA figure is missing or blank on EfficiencyCauseCoverage absent, or the entity has no vendor identityWhat to doRead the coverage line. Link identities on People. A blank is not a zero.
Symptom or error"No spend budget is set for this team."CauseNo guardrail with a budget governs the teamWhat to doSet one on Guardrails if you want a standing line.
Symptom or error400 invalid_request query parameter "principal_kind" is required and must be "identity" or "key"CauseThe generic usage route was called without a valid kindWhat to doPass principal_kind=identity or principal_kind=key.
Symptom or error404 not_found "key not found"CauseUnknown, cross-team or management key idWhat to doUse a runtime key id from API keys.
Symptom or error409 on an identity readCausePrincipal-key coverage marker not yet setWhat to doUse principal_kind=key until the rollout completes.
Symptom or error403 forbiddenCauseThe management key lacks usage:readWhat to doIssue a management key with that scope, or one with no scopes.

Next steps

Ready to keep going?

Explore the next guide or start routing through Nautili.