Run receipt micros: 5,000,000 is $5.00 and 240,000 is $0.24

A Sume run receipt reports money in USD micros, where 1,000,000 micros is one dollar. The Agent Completion receipt in the docs shows usage.generation_spend_cap_usd_micros: 5000000, which is a $5.00 cap. The Format run webhook example shows billable_amount_usd_micros: 240000, which is $0.24 of generation spend, against a cap of 1000000, which is $1.00.

The request side is in dollars: generation_spend_cap_usd: 2 means $2.00, and the receipt echoes it as 2,000,000 micros. Mixing the two units is an easy way to show a customer a cap that is a million times too high.

Reading the numbers safely

Divide by 1,000,000 and keep the arithmetic in integers until display. 240,000 / 1,000,000 = 0.24. In the webhook example, the run used 24 percent of its cap: 240,000 / 1,000,000. Format to cents only at the edge, because a micros value can have more precision than two decimals.

The receipt's usage can be null when Sume cannot read the run's spend. Handle that before you divide. Also note what the field covers: the generation spend that Sume attributes to the run. The docs call GET /v1/usage the authoritative billing record, with reservations, captures, refunds and top-ups as ledger entries.

const MICROS_PER_USD = 1_000_000;

export function usd(micros: number | null | undefined): string | null {
  if (micros == null) return null; // usage can be null
  return (micros / MICROS_PER_USD).toFixed(2);
}

// usd(240000)  -> "0.24"
// usd(5000000) -> "5.00"

Where it goes wrong

Treat null as unknown, not as zero. A dashboard that shows $0.00 for a run whose usage could not be read hides spend. Keep the spend-cap number and the billable number as separate columns, and reconcile against the ledger nightly.

• Do not compare a request in dollars with a receipt in micros without converting.
• The cap is a maximum you accept for the run, not an estimate.
• A cap is required on Agent Completions; a missing value is 400 invalid_request.
• Use the ledger for invoices and the receipt for per-run display.

A reconciliation sketch

For finance reports, sum billable_amount_usd_micros over a day's completed runs as an integer, convert once, and compare with the day's captures in GET /v1/usage. Differences are expected when a run is still in progress, when usage is null, or when a refund is recorded. Treat the ledger as the answer and the receipts as the per-run explanation.

Show the cap next to the billable amount in your UI. A run that used $0.24 of a $1.00 cap tells the operator more than either number alone, and a run that hit its cap is the one to look at first.

Treat this as a habit, not a one-time fix. Write the rule down next to the code that calls the API, add a test that exercises it, and review it whenever the docs change. Check the linked documentation pages in the sources list for the current wording before you rely on any number here, because limits and field names can be revised, and a short test run costs far less than debugging a production incident.

When something does not match what you read here, capture the x-sume-request-id response header and the job or run id, and send those to support. Do not paste API keys, signing secrets or full request bodies into a ticket or a chat; the ids are enough for the team to find the request.