Lower the spend cap for one scheduled Sume run: overrides only go down

You can lower a scheduled run's spend cap for a single trigger but you can never raise it. The API clamps a numeric generation_spend_cap_usd to the smaller of your request and the schedule's cap, so the schedule's cap is the ceiling that only an owner can change in the dashboard (Sume docs: Trigger a schedule by API, read 2026-10-06).

That is a safety property. A script with a bug cannot talk its way past the limit the owner set.

The rules

The default cap for a schedule is $1.00. A number you send must be greater than zero, and 0 is rejected with a 400. Sending null means no automation ceiling, which removes the schedule's own cap for that run; wallet balance, generation admission and organisation limits still apply. Treat null as a decision to make on purpose, not a convenience.

Because requests are clamped, sending a number above the schedule's cap does not error. It silently becomes the schedule's cap. If you expected more headroom, you will find the run stopped at the lower number.

A dry, cheap trigger

The practical use is a smoke test. Before the Monday run, trigger the same schedule with a cap of a few cents and a short input, and see whether it reaches the stage you care about. If it stops on the cap, you learn something without spending the real budget.

import os, requests

H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"],
     "Idempotency-Key": "recap-smoke-2026-10-06"}
url = "https://api.sume.com/v1/actions/acme/weekly-recap/runs"
body = {"generation_spend_cap_usd": 0.25,
        "input": {"week": "2026-W41", "mode": "smoke"}}
r = requests.post(url, json=body, headers=H, timeout=30)
print(r.status_code)
print(r.json()["data"].get("status"))

Raising the ceiling properly

If the real job needs more than the schedule's cap, edit the schedule in the dashboard. The trigger endpoint can only lower the cap for one run; it does not change the schedule's own value. Change the cap in the dashboard, then keep per-run overrides for lowering. Read usage from earlier receipts to choose the new number, and give a little headroom above your worst real run rather than doubling.

Keep an Idempotency-Key on every trigger, between 1 and 255 characters, so a retry replays the first receipt instead of charging twice.

Who can send the trigger

Triggering a run needs an API key with the right scope, and the docs say service-account keys cannot create Action runs at all; they fail with service_account_action_runs_unsupported. So a cap-lowering smoke test has to come from a workspace member's key, which is another reason to keep the trigger script in a place where a person owns it.

The same trigger accepts on_active_run, which defaults to skip: if a run is already active, the API skips the new one and answers 200 instead of 202. A smoke test fired while the real run is going will therefore do nothing, so check the status code and not just that the call returned.

A habit worth keeping

Keep the schedule's own cap near what a normal run needs, not at a high ceiling that you lower per run. A tight default protects you when a trigger fires with no override, which is exactly the case where nobody is watching.

Reading the result of a lowered run

A run that stops on a cap is not a bug in the schedule. Read the receipt's error and usage to see how far it got. If a smoke run with a low cap reaches the stage you wanted to test, you have your answer cheaply. If it stops earlier, raise the cap a little and test again, or move to the full cap with a person watching.

Record what each override was for in your own log. Three weeks later, a receipt with a low cap is a mystery unless the note says it was a test.