Scheduled run cost cap: a per-run cap can only lower it

A scheduled Sume run has a default generation cap of $1.00, and a per-run cap in an API-triggered call can only lower it: the effective cap is the smaller of the request and the schedule. Raise the cap on the schedule itself if you want more headroom.

This is the opposite of the habit most people bring from direct Format calls, where the request's number is accepted as sent. Mixing the two models is how a nightly job stops mid-video.

The cap is also your safety net for a schedule nobody watches. A wrong prompt cannot run past it, so a Monday morning surprise is bounded by a number you chose on Friday.

The scheduled rule

The Create a scheduled run page sets the default at $1.00 and states the rule: the effective cap is min(request, schedule cap). Sending null means no automation ceiling from the request side, so the schedule's cap still applies. A value of 0 is rejected.

If a run hits its cap, you see it as a failed run and the usage block shows the cap that applied. Read that number before concluding the video recipe is broken.

The Format rule, for contrast

On a direct Format run, generation_spend_cap_usd must be above zero and at most 500. A Format with no cap defaults to $400, null means $500, and the API accepts a number above the Format's own cap without clamping. The effective cap appears in usage.generation_spend_cap_usd_micros, so check it rather than assuming.

The two systems protect different things. A schedule is unattended, so its ceiling is conservative and sits on the schedule. A direct call comes from your code, so the request carries the budget.

Choosing a schedule cap

Estimate from a real run, not a guess. Run the Format once by hand and read billable_amount_usd_micros, which counts generation only. The debited_usd_micros field includes the language model turn, so it is the number your wallet saw. Set the schedule cap a little above the debited figure for a typical run, not for the worst case, and let a failure tell you when something is unusual.

If you find a $1.00 default too low for video, raise it on the schedule and keep per-run overrides for cheaper variants.

Revisit the cap when the Format changes. A package edit that adds a scene or a longer clip can raise the real cost above a cap you set for the old recipe, and the first sign will be a failed run.

What happens when it overlaps

The on_active_run setting for a schedule defaults to skip. If the previous run is still going, the new trigger returns 200 with status skipped and skip_reason previous_run_active, and no money moves. Setting reject returns 409 action_run_in_progress instead. For a video that takes 15 to 30 minutes, an hourly schedule is safe, while a five-minute cron would skip most of its fires.

Pair the cap with the overlap rule and a nightly job has two independent brakes.

Remember that a skipped run is not a failure. Count skips separately in your dashboard, because a rising skip rate means the schedule fires faster than the job finishes.