Does a failed Format run cost money? What bills and what is free

Mostly no, with one exception that surprises people. A 4xx at create, an idempotent 200 replay and a skipped run cost nothing, but generation that finished before a cancel or a later failure is billed, and a failed final step does not refund the clips that already rendered. The receipt and the usage ledger tell you which case you are in.

Which cases are free?

The Formats errors page is explicit: a 4xx at create, an idempotent 200 replay, and a skipped run cost nothing. A 402 at create means the wallet gate refused the run and nothing ran. Sending the same Idempotency-Key with the same body returns the original run and does not start a second one.

Why is finished work billed after a failure?

Because the money was spent on a real render. The docs say generation that finished before a cancel or a failure is billed, and a later step failing does not refund it. Sume reserves the estimated amount at submit, captures it on completion, and releases or refunds a reservation only where work did not complete, as described in Generation admission.

A run that cannot finish comes back failed, never a half-finished completed. For example, an unattended run that cannot reach a required paid step is reported with an error code such as unattended_blocked rather than a thin success.

How do I see what a run actually cost?

Read the receipt's usage object, then confirm in the ledger. usage.billable_amount_usd_micros climbs while the run is in flight, counts both reserved and captured amounts, and settles when the run ends. The docs call it a receipt figure rather than an invoice: it excludes the agent's own LLM turn, and usage is null when spend could not be read, which is different from 0.

The billing record is GET /v1/usage, which accepts run_id. Its summary carries debited_usd, held_usd_micros and refunded_usd_micros, and final turns true once no hold is open.

curl "https://api.sume.com/v1/usage?run_id=$RUN_ID&limit=50" \
  -H "Authorization: Bearer $SUME_API_KEY"
# quote summary.debited_usd, not the sum of the rows

What should I do to limit exposure?

Set a run-level cap sized to the work, since a failed run can still keep the money for steps that finished. Send the same idempotency key on every retry of a create, and use a new key only for a genuinely new run. Do not sum ledger rows yourself: a refunded row keeps its hold amount in billable_amount_usd_micros, so the summary is the figure to quote.