Scheduled run spend cap: a request can lower it, never raise it
A Sume schedule's per-run cap is min(request, schedule cap). A $3 request on a $1 schedule runs at $1; null removes the ceiling; 0 is a 400.
When you start a schedule run over the API, generation_spend_cap_usd can only make the cap smaller. The API clamps a positive number to the smaller of your request and the schedule's own cap, so asking for $3 on a $1 schedule runs at $1. Sending null runs without the automation ceiling, and sending 0 is rejected with a 400.
If the schedule has no cap set, the default of $1.00 (1,000,000 USD micros) applies. Wallet balance, generation admission and org limits still apply in every case, including null, so null is not unlimited spend; it only removes this one ceiling.
What each request value does
Example schedule cap: $1.00. Read from the Scheduled and API-trigger pages, 2026-10-09.
| Request `generation_spend_cap_usd` | Effective cap | Why |
|---|---|---|
| omitted | $1.00 | Schedule cap applies |
| 0.50 | $0.50 | min(0.50, 1.00) |
| 1.00 | $1.00 | min(1.00, 1.00) |
| 3 | $1.00 | Cannot raise the cap |
| null | No automation ceiling | Wallet, admission and org limits still apply |
| 0 | Rejected | 400 |
Using it as a guardrail
Because the request can only lower the cap, a service that starts schedule runs can pass a tighter number per run without fear of overspending the saved limit. Raise the limit by editing the schedule in the dashboard, where the saved cap lives; the Developer API cannot create or edit schedules.
The danger is the null case. A client that forwards user input into the field could remove the ceiling, so validate it in your own code and never pass null from a path an end user can influence.
Reading what was spent
The run receipt carries usage with billable_amount_usd_micros and generation_spend_cap_usd_micros, or null when Sume could not read the spend. The total includes reserved and captured amounts and grows while the run is in flight, so compare it against the cap only after the run is terminal. GET /v1/usage remains the authoritative billing record.
A run that hits its cap does not fail silently; the docs have a dedicated 402 automation_generation_spend_cap_exceeded page worth reading before you pick a cap too tight for the task.
Choosing a cap for a real task
Work backward from the catalog. A schedule that makes one 8-second Seedance 2 clip at 720p spends 8 x $0.378 = $3.024, so a $1.00 default cap would stop it. Raise the saved cap in the dashboard to something like $4.00, then let the API caller pass $3.50 for a lighter variant of the same run. The saved cap is the ceiling you trust everyone with; the per-run number is how a single call stays under it.
Remember that the cap covers generation spend only. It is not a reservation of that amount in your wallet at the start, and the wallet check still happens separately at admission. Keep both numbers in view when you size a balance for a batch of scheduled runs: a month of daily runs at a $4.00 cap can reach $120.00 if every run uses its full cap.
Sources
Related posts
More in Agents
- script_run limits: timeout 5-55 s, max_calls and max_paid_calls
Sume's script_run runs a short script of MCP tool calls with a 5 to 55 second timeout and caps on calls and paid calls. What it returns and cannot call.
- Seedance 2.5's 4-second minimum costs $1.07 at 480p 9:16
Seedance 2.5 accepts 4 to 30 seconds, and the shortest 480p 9:16 clip is $1.074709, over the $1.00 default schedule cap. Price points and what to do.
- Six locales, six Agent Completions at $2 each: a $12 worst case
One Agent Completion per locale, each with its own spend cap and Idempotency-Key. Six runs at $2 bound generation to $12, and a retry cannot start a seventh.
- Canceled and skipped Sume agent runs send no webhook: what to poll
A Sume run webhook fires only when a run completes or fails. Canceled and skipped runs send nothing, so your scheduler must read status_url for them.
Written by Sume