Metering & cost

Two things are written for every request that reaches the Gateway. A priced ledger row in token_usage, which carries the price that was applied at request time, and a trace row in gateway_requests, which carries the status code, the latency and the failure class. Both are best-effort by design: neither may fail a completion a provider has already charged for.

Three meters exist, because three different things are sold, and the counters mean different things on each. x-lobstack-quota-meter names the one that applied, and it is the header to branch on before reading any of the others.

A spend meter sends dollars and no request counters. A zero in x-lobstack-quota-limit reads as "no allowance" to a client that cannot tell which meter it is on, so the counters are absent rather than zero. The rule runs the other way too: a legacy subscriber who bought messages is never sent a dollar figure they did not agree to be measured in.

These are advisory for agent credentials and enforced for API keys. Errors & retries covers the 402 and the retry-after that comes with it. All of them are omitted when there is nothing to measure against — no agent row and no org.

Only requests that returned below 400 count against a request or legacy org allowance, so a provider outage on our side does not consume your quota.

The last chunk before [DONE] carries token counts in the standard usage object and the money beside it under x_lobstack. An SDK that does not know us parses the usage object unchanged and ignores the rest.

Read the price from here rather than pricing the token counts against your own copy of our rate card. A local copy drifts: we serve 26 models today and retire or reprice some of them every few weeks, and a client that cannot price the model our router chose will show $0.00 for a request that is on your bill.

cost_usd is null, never 0, when the served model is not in the registry or the stream ended before it could be metered — priced tells you which case you are in. Render a null as unknown; rendering it as free writes off a real charge.

The three baseline fields are sent together or not at all, and savings_usd never travels without baseline_reason. What the two reasons mean, and why they are not interchangeable, is the next section.

A saving is a subtraction, and a subtraction is honest only when the reader can see both operands and where the first one came from. So a baseline never travels without the reason it exists. The saving is always what these exact token counts would have cost on the baseline model, minus what they actually cost, priced on the same basis so the subtraction is between two comparable numbers.

x-lobstack-savings-pct follows a different rule and is present on every response. It is one minus the selected tier's cost multiplier over the ceiling tier's: an estimate about tiers, not a measurement about dollars. It is not a rounded version of the dollar figure and the two should never be added together.

On a plan that carries it, 50% of a verified saving is added back to that period's allowance. Verified is the whole of the rule, and every one of these must hold or the credit is zero.

Routing does not always find something cheaper, and on the calls where it does not there is no saving and no credit. Nothing here promises a saving of any size; the credit is a share of whatever is actually measured, which is sometimes nothing.

The credit is computed on every qualifying request, reported in the meter result, and accrued into spend_allowances — one row per payer per billing period — through an atomic SQL function, so concurrent requests cannot lose a credit to a read-modify-write. The row survives plan changes and subscription churn, because a balance the customer earned should not be stranded on a cancelled subscription mid-period. What each plan credits, and which plans meter spend at all, is on Pricing & plans.

One row per inference round in token_usage, including rounds that failed with zero tokens, so an error rate stays computable from the ledger alone.

The row carrying its own price is the point. Editing the model registry later cannot retroactively move a historical invoice, because nothing recomputes an old row from the current catalog.

When the served model key is not in the registry, the price is recorded as null, not zero. A missing price is a gap in the catalog; recording it as free would silently write off real spend, which is the most expensive way to be wrong here. The response reports x-lobstack-priced: false and the header value for cost is empty.

Every one of these is logged loudly on the server and counted in the usage rollup as an unpriced request. If you see one, the fix is a registry entry or an alias, not a default. This is also why aliases resolve for pricing and not only for routing: a live agent once ran on a spelling the resolver did not know, and every request it made metered free.

Org-scoped usage, traces and latency. Two credentials work: a browser session, which is what the Console reads, and an API key carrying the usage:read scope. Both get identical numbers from identical arithmetic rather than each computing their own.

Query parameters: range (7d, 14d, 30d, 90d; default 7d), group_by (day, model, key, agent; default day), agent_id and key_id.

Percentiles are true percentiles over the raw latency values, not an average of per-bucket averages — which is the usual way a dashboard ends up reporting a p95 nobody experienced.

truncated is true when the row cap bound, at which point the sums are a floor rather than a total and the response says so instead of handing you a confident wrong number. Narrow the range or filter by key.