Continued Format run: artifacts span the thread, usage is per run

When you continue a Format run with previous_run_id, the new run is a separate receipt with its own spend, but its artifacts[] lists everything the whole conversation generated. usage stays per run. So the artifact list of a continuation is not a count of what that one run made, and adding artifact counts across runs of one thread double counts. Use usage for money and primary_output_url for the deliverable.

What does a continuation share with the original?

A Format run is one agent turn. Naming previous_run_id on a new POST …/runs makes the next turn continue the same conversation: the agent is replayed what it produced, so it can redo one part and leave the rest alone. The original run never changes.

The table lists what is shared and what is new.

Which run can I continue?

Read it off the run's own receipt: thread_id must not be null, and the run either completed or has a non-empty artifacts[]. A failed run that left work behind can be continued; one that left nothing cannot. You continue by naming previous_run_id, never by sending a thread id, which is 400 unknown_parameter.

Refusals have their own codes: 404 previous_run_not_found, 400 previous_run_format_mismatch when the run belongs to a different Format, 409 previous_run_not_terminal, and 400 previous_run_not_resumable.

How do I count cost and output correctly?

For money, read each run's usage, or ask the ledger for the whole thread with GET /v1/usage?thread_id= or one run with ?run_id=. The usage page warns against summing rows yourself, because a refunded row keeps its hold amount in billable_amount_usd_micros.

For output, key on the run, not on the artifact list. A scene retry costs a fraction of the show and returns the full set of clips on the thread, so a UI that renders artifacts[] of the newest run shows the unchanged scenes too. That is usually what you want; it is just not a per-run tally.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/live-commerce/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-lc-v1-retry-sc7" \
  -d '{
    "previous_run_id": "arun_e43e6c5cb2b74052",
    "instruction": "Retry the selected scene only. Keep every other scene unchanged.",
    "input": { "scene_id": "sc_7" },
    "primary_output_key": "full_video",
    "generation_spend_cap_usd": 8
  }'

Anything else to watch?

Bind the same output_schema and primary_output_key on the continuation, since neither is inherited. Send a fresh Idempotency-Key derived from the order and the retry, not a reused one: a different body under a spent key answers 409 idempotency_conflict.

What does a continuation look like in a UI?

A product page for a generated show usually wants three things: the final video, the per-scene status, and a cost line. Take the final video from primary_output_url, the scene status from your own output_schema, and the cost from usage. Keep a small record per order that maps your order id to the original run id and each continuation's run id, because previous_run_id lives on the continuation's receipt. Walking the chain backwards from the newest run is possible from receipts alone; walking forwards from the original is easiest with your own index.