Why a Sume run's billable_amount_usd_micros is not its total cost

usage.billable_amount_usd_micros on a Sume Scheduled run receipt is the generation spend attributed to that run, not the run's total cost. It leaves out the agent's own LLM turn, which bills a separate Agent wallet, and it is a receipt figure rather than an invoice.

This is spelled out in Runs and results. Read it before you build a cost dashboard on top of webhooks.

What does the number include?

It is the same running total that the run's generation_spend_cap_usd_micros is enforced against, counting both reserved and captured amounts. It climbs while the run is in flight and settles when the run terminates. One USD micro is a millionth of a dollar, so 240000 means $0.24.

You can see the figure rise while the run is in flight and settle at the end, so for accounting read it once after the run is terminal. A run that fails can still show spend, since generation that already completed was billed.

What does it leave out?

Two things, per the docs. First, the agent's own LLM turn bills the separate Agent wallet, so it is not in this figure. Second, it is a receipt, and GET /v1/usage remains the authoritative billing record.

The practical consequence: a run showing billable_amount_usd_micros: 0 may still have used the agent model. Zero means the run has not spent generation money yet, not that it was free.

What does a null usage mean?

usage is null when spend could not be read at all. That is distinct from 0. Handle both: a null should make your dashboard show unknown, not zero, and send you to GET /v1/usage for the number.

The same figure appears in the run webhook, as payload.usage, because the webhook payload is the receipt itself.

A null usage also tells you something: if it happens often, log the request_id and ask for an investigation instead of assuming zero. The docs call request_id the fastest way to get a run investigated.

How should you track spend correctly?

Use the receipt for per-run guardrails and GET /v1/usage for money. A simple split:

It helps to keep three numbers apart in your own reports: the cap you allowed, the generation spend the receipt attributes to the run, and the billing record from GET /v1/usage. The cap bounds the second number, and the agent's own LLM turn sits outside the receipt figure, so receipts alone understate what a run cost.

• Set a per-run generation_spend_cap_usd on the run request (it can only lower the Action's cap) so the ceiling is enforced regardless of what you track.
• Log request_id and billable_amount_usd_micros per run for a quick per-run view.
• Reconcile against GET /v1/usage at the end of the day rather than summing receipts.
• Do not describe the receipt figure to finance as total cost.