Format run spend caps: $400 default, $500 maximum, and what null does

Every Sume Format has a generation spend cap, and a run can never spend more than its effective cap. A Format that never named one reports the platform default of $400. On a single run you can set generation_spend_cap_usd to any number up to $500. Send null and you get the platform maximum, $500. Send 0 or a number above 500 and you get a 400.

How the effective cap is chosen

Reading the cap on a receipt

Read the Format's default cap as generation_spend_cap_usd_micros from GET /v1/formats/...; $400 is 400,000,000 micros. Every receipt shows the effective cap as usage.generation_spend_cap_usd_micros and the spend so far as usage.billable_amount_usd_micros, so a monitor can compute the share used. In the docs example a $120 cap appears as 120000000, and a finished run shows 14959638 micros, about $14.96, or roughly 12.5% of it.

The docs say production live-commerce integrations run with caps of approximately $120, and that a single-scene retry on the same thread needs a fraction of that.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/live-commerce/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capped-001" \
  -d '{
    "instruction": "Use the script as written.",
    "generation_spend_cap_usd": 25
  }'

Caps in bulk and retries

A cap is per run, not per batch. In a 20-item bulk queue each item can carry its own generation_spend_cap_usd, so the worst case for the batch is the sum of the item caps: 20 items at $120 is up to $2,400. A single-scene retry on the same thread needs a fraction of the original cap, so retries do not need the original number.

Keys also matter: a run is billed to the workspace of the key that made the call, and a team Format needs a key created in that team's workspace.

Cap or no cap

There is no way to run with no cap at all. null lifts the ceiling to $500 but does not remove it, and the docs describe it that way on purpose. If a Format regularly needs more than $500 per run, split the work into several runs on the same thread instead, for example one per scene, which also limits the cost of a failed run to the cap of one scene.

Choosing a number

Because Sume does not clamp a number above the Format's cap, a request can raise the ceiling. Treat the cap as a safety net, not a quote: set it to a comfortable multiple of what a typical run spends, and watch billable_amount_usd_micros on completed runs to tune it. In a bulk queue each item can carry its own cap.

A separate failure is 402 insufficient_credits, returned when the workspace cannot fund the run; its next_action is add_funds. Spend meters at the rates on the Sume API pricing page.