Scheduled run spend cap: a per-call number can only lower it
A Sume schedule's default generation cap is $1.00. A per-run number is clamped to the lower of the request and the schedule cap, and 0 is rejected.
On a Sume schedule, a per-run generation_spend_cap_usd can lower the cap but never raise it: the API clamps a number above zero to the smaller of your request and the schedule's own cap, null runs without the automation ceiling, and 0 is rejected (Scheduled). If a schedule has no cap of its own, the default is $1.00.
How a request resolves
Assume a schedule with a $1.00 cap.
| Per-run value | Effective cap | Why |
|---|---|---|
| 0.25 | $0.25 | Lowered by the request |
| 1 | $1.00 | Equal to the schedule cap |
| 5 | $1.00 | Clamped to the schedule cap |
| 0 | 400 error | The API rejects 0 with 400 |
| null | No automation ceiling | Runs without the schedule cap |
An API-triggered run
Only schedules with api_trigger_enabled accept POST /v1/actions/{action_id}/runs; trigger_type is fixed at create time.
curl -sS -X POST "https://api.sume.com/v1/actions/$ACTION_ID/runs" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: weekly-teaser-2026-w41" \
-d '{"generation_spend_cap_usd": 0.25}'Other limits
| Limit | Value |
|---|---|
| input properties | 64 |
| input size | 2 MiB |
| Idempotency-Key length | 1 to 255 characters |
| list limit | 1 to 100, default 50 |
Practical use
Set the real ceiling on the schedule in the dashboard and use the per-run number only for cheaper one-off runs. Raising spend means editing the schedule, not the request.
The null caveat
null is the one value that removes the automation ceiling, so do not send it from an unattended client that you expect to stay capped. Wallet balance, generation admission and organization limits still apply, as the API-trigger page notes. Sending a bare number above zero is the safe way to tighten a single run.
Sources
Related posts
More in Agents
- A Sume image job at 50 seconds: slow, queued, or stuck?
Sume's docs say an image still running after a 50 s jobs_wait is usually stuck, not slow. Check queued vs processing and events first; never submit twice.
- Sume MCP avatar tools: 5 read-only and the paid create set
Hosted Sume MCP lists five read tools for avatars and avatar videos and a paid group for creates and previews. What OAuth mcp:read sees and the dry_run flow.
- Keep untrusted text out of the prompt: Sume run input is data only
Sume writes a run's input object to a file and treats it as data, not instructions. Schedule runs allow 64 properties and 2 MiB. Use it as a guardrail.
- Schedule fires while the last run is active: skip or reject?
Sume schedule API runs default to on_active_run skip, which returns 200 with a skipped receipt. reject returns 409 action_run_in_progress. When to pick each.
Written by Sume