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.

The response headers

Routing

There is no x-lobstack-requested-model. Nothing on a buffered response echoes the model key you sent, and that is a stated absence rather than a gap in this table — you already hold what you sent, so what is worth a header is what came back instead. Compare it against x-lobstack-model, and read x-lobstack-routed for the comparison already made: it is true when auto selected a model. A named model is exact, so it is always false on a successful exact call.

When you need it back from us rather than from your own call site, it is recorded rather than headered: requested_model on the streamed response's x_lobstack frame, on the token_usage ledger row, and on the trace row that GET /api/v1/requests, the usage API and Console → Logs all read. On an auto request every one of those says auto, which is the honest answer and not a missing value.

Cost

Quota

Three meters exist, because three different things have been 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.

They are enforced for every credential: at the limit a call gets a 402. 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.

Cost on a streamed response

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 18 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.

{
  "id": "chatcmpl-2f1c…",
  "object": "chat.completion.chunk",
  "model": "gemini-3.8-flash",
  "choices": [],
  "usage": { "prompt_tokens": 1000, "completion_tokens": 500, "total_tokens": 1500 },
  "x_lobstack": {
    "request_id": "2f1c…",
    "served_model": "gemini-3.8-flash",
    "requested_model": "claude-opus-5",
    "routed": true,
    "cost_usd": 0.0039375,
    "provider_cost_usd": 0.002625,
    "rate": "provider price + 50%",
    "savings_usd": 0.0144375,
    "priced": true,
    "baseline_model": "claude-opus-5",
    "baseline_reason": "named",
    "baseline_cost_usd": 0.018375
  }
}

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.

rate says how cost_usd was produced from provider_cost_usd: provider price inside the plan's included usage, provider price + 50% past it, and provider price, then provider price + 50% on a call that crossed the line. The sample above is a call past it.

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.

The baseline rule

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.

Savings credit

The credit share is currently 0%: a verified saving shows on the receipt and the ledger and extends no allowance. The rule below is what verified means, and it still decides what the receipt reports. Verified is the whole of the rule, and every one of these must hold or the saving 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.

What a ledger row records

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.

Unpriced requests

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.

The usage API

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.

curl "https://www.lobstack.ai/api/v1/usage?range=30d&group_by=model" \
  -H "Authorization: Bearer $LOBSTACK_API_KEY"

{
  "enabled": true,
  "org_id": "…",
  "authenticated_via": "api_key",
  "range": "30d",
  "group_by": "model",
  "summary": {
    "requests": 18412,
    "errors": 96,
    "error_rate": 0.0052,
    "errors_by_class": { "provider": 71, "validation": 19, "timeout": 6 },
    "prompt_tokens": 9140233,
    "completion_tokens": 1882901,
    "total_tokens": 11023134,
    "cost_usd": 41.283914,
    "p50_latency_ms": 812,
    "p95_latency_ms": 3140,
    "p99_latency_ms": 7602,
    "streamed": 11208
  },
  "groups": [
    {
      "key": "claude-sonnet-5",
      "requests": 6120,
      "errors": 21,
      "total_tokens": 5011882,
      "cost_usd": 24.117,
      "p50_latency_ms": 940,
      "p95_latency_ms": 3402
    }
  ],
  "truncated": false
}

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.