Fire a cron schedule on demand: api_trigger_enabled, cron kept

To start a Sume cron schedule on demand, turn on its API trigger and call POST /v1/actions/{action_id}/runs. A cron schedule can also enable api_trigger_enabled, so it accepts API runs on top of its cadence and keeps firing on time. You do not have to convert it to an API-only schedule, which is just as well: the trigger type is fixed at create time, so a cron schedule can never drop to API-only.

What must be true before the call works?

Every run request needs three things: the schedule's status is active, its api_trigger_enabled is true, and your key carries actions:read and actions:write. Keys created before the API-call trigger shipped do not carry those scopes, and scopes cannot be added to an existing key, so mint a new one.

What happens if the cron run is in flight?

Only one run of a schedule is active at a time. on_active_run decides what a second request does, and on Scheduled the default is skip: the call returns 200 with a receipt whose status is skipped and skip_reason is previous_run_active. A run row is recorded. Send reject instead and you get 409 action_run_in_progress with no run recorded.

That makes the HTTP status a poor signal. A 200 is either an idempotency replay or a skipped run, and a 202 is a run that started. Branch on the receipt's status, not on the code.

How do I tell the runs apart afterwards?

The receipt's trigger.source is cron, manual or api, and the run history labels runs started through the API API and scheduled ones Cron. A per-run generation_spend_cap_usd can only lower the schedule's cap, never raise it; unset, the effective cap is $1.00 per run.

Send an Idempotency-Key on every on-demand call, 1 to 255 characters. The same key with the same payload returns 200 with the original receipt and idempotency_hit: true; a different payload under the same key is 409 idempotency_conflict.

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-manual" \
  -d '{"input": {"campaign": "summer-2026"}, "on_active_run": "reject"}'

When is an API-only schedule the better choice?

Choose API-only at create time when an external system, not a clock, should decide when work happens: it persists trigger_type: "api" and drops the cadence entirely. Choose cron with the API trigger enabled when the clock is the main driver and you only need an occasional manual run, for example a weekly teaser that marketing sometimes wants right now. The choice is permanent either way, so decide before you create the schedule: an API-only one can never gain a cadence.