Can a per-run spend cap raise the limit? Formats yes, schedules no

It depends on the surface. On a Format run, a generation_spend_cap_usd above the Format's own cap is honored, not clamped. On a scheduled agent, a per-run value can only lower the schedule's cap, never raise it. On an Agent Completion there is no default: omit it and the request fails with 400 invalid_request.

How do the three surfaces differ?

All three take a per-run generation_spend_cap_usd, and the defaults and ceilings are different enough to cause surprises when you move code between them. The table is from the Sume docs for each surface.

Why would a Format honor a higher cap?

The Format's cap is a default for runs that do not name one, and the docs say a run "can never spend past its own effective cap". A single-scene retry needs a fraction of a long-form run, and a rare big run may need more than the default, so the caller is allowed to set the ceiling for that run, up to $500.

The docs also warn that null "lifts the ceiling; it does not remove it": the run is capped at $500, not left uncapped. Production long-form runs are typically created with caps around $120.

Why do schedules clamp instead?

A schedule runs unattended on a clock. The schedule's cap is set by the person who made it, and the per-run override is clamped to min(request, schedule cap), so a stray API caller cannot raise it. The null case is narrower than it sounds: it removes the automation ceiling, but wallet balance, generation admission and org limits still apply.

curl -X POST "https://api.sume.com/v1/formats/$HANDLE/$SLUG/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"instruction": "Make the 30-second spot", "generation_spend_cap_usd": 120}'

How should I choose a cap?

Size it from the rate card on the API pricing page, plus headroom for retries, and set it per run rather than relying on a default. Read the effective cap back from the receipt as usage.generation_spend_cap_usd_micros. If you port a call from a Format to a schedule, expect the clamp: a $120 request against a $1.00 schedule cap runs at $1.00.