Billing & Spend Events

• Nothing is silently missing. A request whose confirmation never arrived still produces an event, typed settled, with its cost marked unknown rather than zero. The worst case is a recorded request with an unknown cost, never a missing request.
• Everything is idempotent. Event ids are stable across retries and replays. Recorded spend is never mutated: budget resets move period boundaries, corrections arrive as new events, and the ledger is append-only.
• Push and pull agree. The pull surface serves the same canonical envelopes the webhooks deliver, from the same ledger, so a checksum mismatch means something real.

​

The spend event

{
  "event_id": "01K1D3H8ZQ4M9X2C7V5B1N6P8T:completed",
  "event_type": "gateway.request.completed",
  "gateway_request_id": "01K1D3H8ZQ4M9X2C7V5B1N6P8T",
  "occurred_at": "2026-07-27T14:03:11.482Z",
  "organization_id": "org_01H...",
  "project_id": "proj_01H...",
  "virtual_key_id": "vk_01H...",
  "principal_user_id": null,
  "end_user_id": "d7dcef1e-0755-4ad1-b31a-c253fc27e8bf",
  "trace_id": "cbabd1d8-4f...",
  "model": "bedrock/global.anthropic.claude-sonnet-5",
  "model_provider_id": "mp_01H...",
  "request_type": "chat_completions",
  "usage": {
    "input_tokens": 869,
    "output_tokens": 207,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "reasoning_tokens": 0
  },
  "cost": {
    "total_usd": "0.003808",
    "nano_usd": 3808000,
    "rate_version": "2026-07-15"
  },
  "status": "success",
  "needs_reconciliation": null,
  "settle_reason": null,
  "error": null,
  "duration_ms": 3878,
  "labels": ["tier:pro"],
  "metadata": { "tenant_org": "acme-172", "environment": "production" }
}

• event_id is the envelope id: the gateway request id with a type suffix. Dedup on it. gateway_request_id is the plain join key across the settled and completed pair, and it is the same ULID your client received in the X-LangWatch-Gateway-Request-Id response header, so you can join request-side logs to billing events.
• occurred_at is request time, never ingest or delivery time. Late events land in the right invoice period.
• status is success or error on completed events. Failed provider calls are events too; error carries {class, http_status} so your billing decides whether to charge for them.
• end_user_id is the attributed end user (see attribution). metadata is your caller echo, returned verbatim: this is how billing joins events to your own tenant and user records.
• model_provider_id names the provider credential that actually served the request.

​

Money representation

• Quantities are exact integers per token class: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, reasoning_tokens.
• Cost is cost.nano_usd, an int64 in billionths of a USD ($0.003808 arrives as 3808000), together with rate_version, the pricing catalog version used to rate it. total_usd is a display-friendly decimal string of the same amount.
• Never parse floats for money. Sum the integers; round exactly once, at invoice time. Currency is USD, single and stated.

​

Settled events and supersession

{
  "event_id": "01K1D3H8ZQ4M9X2C7V5B1N6P8T:settled",
  "event_type": "gateway.request.settled",
  "gateway_request_id": "01K1D3H8ZQ4M9X2C7V5B1N6P8T",
  "usage": null,
  "cost": null,
  "duration_ms": null,
  "status": "settled",
  "needs_reconciliation": true,
  "settle_reason": "confirmation_deadline_expired"
}

• Quantities, cost, and duration are null: unknown is not zero. Never book a settled event as $0.
• A settled request never appears in the completed stream, so your billing can trust completed for money and treat settled as a work queue.
• If the confirmation later arrives, a real gateway.request.completed for the same gateway_request_id follows and supersedes the settled event. Your consumer replaces the settled figure with the completed one. Replace, never sum. The type-suffixed event ids exist precisely so your dedup layer does not swallow the second event.

​

Attribution: what the request carries

• End-user id resolution precedence: the x-langwatch-end-user-id header, then x-litellm-end-user-id (a migration alias, accepted so LiteLLM-shaped clients need no change), then the OpenAI user body field. Headers win over the body.
• Metadata echo: send x-langwatch-metadata (a JSON object, 4 KB cap). It returns verbatim as metadata on every spend event for that request.
• Request id: every gateway response carries X-LangWatch-Gateway-Request-Id, the same ULID that keys the spend event.

​

Reconciliation: two grains, one ledger

​

Fast path: aggregate checksums

GET /api/gateway/v1/spend-summaries?group_by=virtual_key&from=1751328000000&to=1753920000000

{
  "key": "vk_01H...",
  "event_count": 18412,
  "settled_count": 3,
  "usage": {
    "input_tokens": 10233801,
    "output_tokens": 2214410,
    "cache_read_input_tokens": 3400122,
    "cache_creation_input_tokens": 90212,
    "reasoning_tokens": 0
  },
  "cost": { "total_usd": "184.402117", "nano_usd": 184402117000 }
}

​

Item diff: the cursor walk

GET /api/gateway/v1/spend-events?from=1751328000000&to=1753920000000&cursor=...

• from and to (unix milliseconds) are required, must be safe integers, and from <= to; the walk is a ranged read by contract.
• Pages are stable under live writes: rows are served in insert order, so a row folded late is picked up by a later page of the same walk instead of being skipped. Offset pagination cannot promise that; cursors can.
• Filters: virtual_key_id, end_user_id, project_id, model, and status (success, error, admitted, confirmed, failed, settled). limit defaults to 50, max 200.
• Rows come back as the same canonical envelopes the webhooks deliver, plus next_cursor. Diff by gateway_request_id.
• A garbled cursor is refused with 400 rather than silently restarting the walk.
• In-flight requests appear with status=admitted and null quantities (typed gateway.request.admitted on this surface only; they are never pushed). Treat them as not yet billable.

​

The settled work queue

​

Retention

​

Per-end-user spend

GET /api/gateway/v1/end-users/:end_user_id/spend

{
  "data": {
    "end_user_id": "d7dcef1e-0755-4ad1-b31a-c253fc27e8bf",
    "window": "month",
    "from": "2026-06-27T14:03:11.482Z",
    "to": "2026-07-27T14:03:11.482Z",
    "cost": { "total_usd": "0.412209", "nano_usd": 412209000 },
    "request_count": 218,
    "usage": {
      "input_tokens": 184220,
      "output_tokens": 41022,
      "cache_read_input_tokens": 0,
      "cache_creation_input_tokens": 0,
      "reasoning_tokens": 0
    },
    "caps": [
      {
        "budget_id": "bgt_01H...",
        "anchor_id": "vk_01H...",
        "window": "month",
        "on_breach": "block",
        "limit_usd": "25",
        "spent_usd": "0.412209",
        "period_started_at": "2026-07-01T00:00:00.000Z"
      }
    ]
  }
}

• The rollup (cost, request_count, usage) reads the spend ledger over a rolling window: window is day, week, or month (last 24 hours, 7 days, or 30 days, defaulting to month), and explicit from/to in unix milliseconds override it.
• caps is every attributed-user template in your organization that applies to this user, each carrying its current budget period spend, boundary-aware, which is the figure enforcement uses. That period is the budget’s own, so it will not match the rolling rollup above unless the two happen to align; the rollup is for showing usage, caps is for showing headroom. An empty array means no template applies to that user.
• virtual_key_id narrows both the rollup and the caps to one anchor key.

​

Replay

POST /api/gateway/v1/spend-events/replay
{"from": 1753747200000, "to": 1753833600000, "endpoint_id": "whep_01H..."}

• The window is capped at 7 days per call, and a window holding more than 10,000 envelopes is refused with a request to narrow it.
• The response reports {endpoint_id, replay_id, replayed, window}; replay_id identifies this replay in delivery bookkeeping without touching envelope ids.
• Downstream dedup windows are finite (Metronome documents 34 days, Stripe meters 24 hours and up). Replaying a range older than your billing system’s dedup window can double-bill on your side. For old ranges, prefer pull-and-diff over replay.

​

The ledger UI

​

Operational notes

• Failed requests are events. Decide explicitly whether your billing charges for provider errors; status and error give you the branch.
• Blocked requests are not. A request rejected before dispatch (budget breach, missing end-user id, disabled key) produced no provider spend and no spend event. The rejection is visible on the budget events and in gateway metrics instead.
• Settlement window: 30 minutes by default. Self-hosted deployments can tune it; see self-hosting webhooks and billing.
• No content, ever. Spend events carry ids, counts, classes, and your metadata echo. Prompts and responses never enter the billing pipe.

​

See also

• Webhooks: endpoints, signatures, retries, health, the events log.
• Metering and rebilling your customers: the end-to-end cookbook, with the runnable demo repo.
• Budgets: caps on tenants and end users, thresholds, resets.
• Virtual keys: the tenant credential, disable and revoke semantics.