Format run stalled or just slow? Read the events phase timeline

To tell a stalled Sume Format run from a slow one, read GET /v1/format-runs/{run_id}/events. It returns a phase timeline of preparing, running and finalizing, and the at on the last entry is the run's progress clock: if it stops moving for several minutes the run is stalled, not slow.

Slow is normal. Long-form video is 15 to 30 minutes of work and most of it is the running phase. Stalled is different, and Sume finalizes such a run as failed at documented bounds, so you do not have to guess how long to wait.

What does the events endpoint return?

A list of phase entries, each with at, phase, status and duration_ms when the phase measured itself. Per the runs page, preparing is everything before the agent has the run in hand, running is the agent working the recipe, and finalizing is teardown and output harvest.

Consecutive entries with the same phase and status collapse into one whose at keeps advancing. That is why you read the last entry's at rather than counting entries: a long healthy running phase is still one row.

When does a silent run get force-finalized?

A non-terminal receipt carries expires_at, the deadline past which the run is force-finalized as failed. It is 90 minutes from created_at, or sooner when the run is older than 25 minutes and has been silent for 10. Use expires_at as your own polling ceiling rather than inventing a timeout.

This means a stalled run does not spend forever, but it can sit for ten minutes before Sume ends it. If you want to act earlier, compare the last at to the clock yourself, and cancel with POST …/cancel if you decide it is dead.

How do I measure the silence?

The sample reads the events and prints how long ago the progress clock last moved. It uses only the Python standard library, and the threshold of five minutes is yours to tune; the docs say "several minutes" without a fixed number.

Poll events sparingly. Polling spends read budget, and there is no push channel for progress; the terminal webhook is the alternative.

import json, os, urllib.request
from datetime import datetime, timezone

def silent_seconds(run_id):
    req = urllib.request.Request(
        f"https://api.sume.com/v1/format-runs/{run_id}/events",
        headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"]})
    with urllib.request.urlopen(req, timeout=30) as r:
        events = json.load(r)["data"]
    last = events[-1]["at"].replace("Z", "+00:00")
    age = datetime.now(timezone.utc) - datetime.fromisoformat(last)
    return age.total_seconds(), events[-1]["phase"]

secs, phase = silent_seconds(os.environ["RUN_ID"])
print(f"last phase {phase}, silent {secs:.0f}s")
if secs > 300:
    print("likely stalled: consider POST /v1/format-runs/{id}/cancel")

What is not in the timeline?

It is a phase timeline, not a log stream. Agent output, tool calls and sandbox internals are not published here and will not be, and the conversation is not available at …/messages. If a run fails, read error and output_error on the receipt, and artifacts[] for what the run made. For a run that never leaves queued, read the queue object instead, as described in the stuck queued post.