Format run spend caps: the $500 ceiling and the null trap

Every Sume Format run has a generation spend cap, and a run can never spend more than its own effective cap. If you omit generation_spend_cap_usd, the run inherits the Format's cap. If you send a number up to 500, that is the cap. If you send null, the cap becomes the platform maximum of $500. That lifts the ceiling, but it does not remove it.

For a holiday batch, the cap is the safety rail. It is the number that decides whether a runaway prompt costs you $12 or $500.

The five cases

The Calling a Format docs define the cap in one table. A Format that never named a cap reports the platform default of $400.

Two traps

Notice that a number above the Format's own cap is accepted and not clamped. A Format capped at $120 will let a single run raise it to $400 if the caller asks. That is a feature when you want a one-off hero render, and a hazard if your batch code builds the cap from user input. Validate the number in your own code.

The null case is the trap. A reader sees 'null' and thinks 'no limit'. In Sume it means $500. If you passed null for forty items in a bulk queue, your worst-case exposure is $20,000, not a number you cannot bound.

Reading the receipt

Every receipt reports usage.generation_spend_cap_usd_micros and the actual spend as usage.billable_amount_usd_micros. Micros are millionths of a dollar, so 14,959,638 is $14.96. Divide by 1,000,000 in your code, and never display the raw number.

Run the arithmetic before you queue. A bulk queue holds 1 to 100 items, so the worst case is items times the per-run cap. A hundred items at a $20 cap bound the queue at $2,000. Choose the cap from the dearest realistic run, not from the average, and then watch billable_amount_usd_micros on finished runs to tighten it.

Choosing a number

The docs note that production live-commerce integrations run with caps of about $120 and that a single-scene retry on the same thread needs a fraction of that. Long-form host video is the heavy case. Short ad runs need far less, so start a batch with a low cap and raise it only for a run that fails for budget.

If a run hits its cap it does not deliver a partial result: the Format docs state that a run never gives a partial delivery, and one that could not finish comes back failed. Plan for that by reading status on every receipt, and re-run with a higher cap or previous_run_id where that fits.

A way to set caps

Here is a simple way to set caps for a holiday batch. First run three items with the cap at a deliberately high value, such as $20, on the dearest SKUs you have. Read billable_amount_usd_micros on each finished receipt. Then set the batch cap to about twice the highest figure you saw. That leaves room for a retry inside the run, and still bounds a bad prompt at a number you chose in advance.

For a bulk queue, the same cap goes on each item, since each item is the same body as a single run and can bind its own generation_spend_cap_usd. The queue itself has no cap field. The total exposure is the sum of the item caps, and the concurrency window only changes how many of them are in flight at once, from 1 to 16.

Keep the cap in configuration, not in the prompt. A recipe that tells the agent 'stay under ten dollars' is not a control. The cap on the request is a control, because the platform enforces it.

The wallet is separate

Finally, read the wallet side. The cap bounds a run, but your workspace still has to hold the credits. The docs point to the errors page for what happens at the wallet. Check that page before a big queue, so that a batch does not stall on a payment error halfway through a sale weekend.