Run a Sume Format on a schedule without overlapping runs

Set on_active_run on the run body. allow (the default) starts the run even if another run of that Format is in flight. skip records a run with status skipped and does nothing else. reject answers 409 format_run_in_progress. Pick skip for a nightly cron that must not stack, and reject when your code should notice the clash.

Why a cron needs it

A Format run takes minutes, and long-form video can take 15 to 30 minutes. A job that fires every hour will sometimes meet a run that has not finished. With allow, both run at once, and workspace generation concurrency still applies. That is correct for independent products and wrong when the second run would repeat the first one's work.

The three values

Scheduled Actions inside Sume default to skip. The docs warn not to copy their bodies into API calls, because your API call defaults to allow.

What skipped means for your code

A skipped run is already terminal on the create response. It never delivers a webhook, and a canceled run does not either. So a skipped night does not wake your receiver, and you should not wait for one.

Treat skipped as a normal outcome. Log it with the idempotency key, and let the next scheduled tick try again. Treat the 409 from reject as a signal: it means a run you started earlier is still working, so read that run instead of creating a new one.

A body that skips

The key is derived from the date, so a retry of the same night replays instead of creating a second run.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-slideshow/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-slideshow-2026-10-05" \
  -d '{
    "instruction": "Make tonights slideshow from the three product photos.",
    "on_active_run": "skip",
    "generation_spend_cap_usd": 40
  }'

See what is in flight, and stop it

GET /v1/formats/{handle}/{slug}/runs takes the same address as the create call, so you can list the runs of a Format and see which ones are still queued or processing. Each receipt also carries a cancel_url. POST /v1/format-runs/{run_id}/cancel stops a run, and the word in the status is canceled with one l.

A canceled run does not deliver a webhook. The cancel call answers you directly. If your scheduler cancels a stuck run and then creates a fresh one, give the new run a new idempotency key, because the old key is tied to the old body and the old run.

• Use expires_at on the receipt as a ceiling. Sume force-finalizes a non-terminal run as failed 90 minutes after created_at.
• Use skip for a periodic refresh of the same asset, where the older run's result is good enough.
• Use reject for a run that a person triggers, so that the person sees the clash.

Bulk queues are different

If you fan out many items with a bulk queue, each child is an ordinary run and runs with allow. The queue's concurrency window sets how many are in flight, not on_active_run. Use a single-run call when you need skip or reject.