Cancel one episode in a running Sume bulk queue: what it frees

To stop one bad episode in a running season, cancel its item run with POST /v1/format-runs/{id}/cancel. Sume has no endpoint to cancel the whole queue, so the other episodes keep going. The canceled item leaves the window, and the next waiting item takes its place.

What to expect

Think of the queue as a conveyor with a fixed number of seats, set by concurrency from 1 to 16. A run that ends in any terminal state, whether completed, failed or canceled, vacates its seat and the next queued episode sits down.

Find the item

The queue lists its items with their run ids. Read it with GET /v1/format-run-queues/{id}, find the episode by the number you put in its input, and cancel that run. If the response says no_op, the run had already finished or been canceled, and nothing changed.

Cancel many, from a script

To drop several episodes, loop over their run ids and read cancel_effect for each. Do not stop at the first no_op, because it only means that run was already terminal.

Cancel is idempotent, so a retry of the same call is safe and answers with the current receipt. cancel_effect tells you whether this call stopped the run (canceled) or the run was already terminal (no_op). Only a run that is queued or processing can be cancelled, and the run receipt shows a cancelable flag you can read first.

import os, requests

H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}
for run_id in os.environ["RUN_IDS"].split(","):
    r = requests.post(
        f"https://api.sume.com/v1/format-runs/{run_id}/cancel",
        headers=H,
        timeout=30,
    )
    r.raise_for_status()
    print(run_id, r.json().get("cancel_effect"))

Money and webhooks

Cancelling stops the run, but work already done may still have been billed, so do not assume a cancel is free. Because no webhook arrives for a canceled run, any downstream step that waits for a delivery per episode has to treat a cancelled episode as a known absence. Keep a list of episodes you cancelled on purpose.

Then what

After cancelling, the queue will reach completed with counts.canceled above zero. That is expected. When you are ready to render the episode again, create a new run with a new idempotency key instead of replaying the old one, which would return the original run.

A common reason to cancel is a script error spotted late: episode 5 has the wrong name in the dialogue, and episodes 6 to 10 are still waiting. Cancel episode 5's run, fix the outline, and send episode 5 again by itself. Because the queue marks the cancelled item terminal, the slot goes to episode 6 at once and the season keeps moving while you repair the one episode.