Restart a failed run from a step
Restarts a failed run from one of its steps as a new attempt of the same run. Requires permission runs:manage.
v2 compatibility notes
A new attempt of the same run
POST /api/v2/runs/restart restarts a failed production run from one of its steps. The run keeps its id and starts a new attempt: the step you name and every step after it run again, and the steps before it keep their results. A restarted step that calls a model spends again. The answer is { "id", "attempt", "status": "running" }; poll GET /api/v2/runs/get for its progress.
The body is exactly { "id", "fromStepId", "capCents"?, "acceptRemainingCap"? }: id is the run’s id and fromStepId a node of the run’s graph (a step’s stepId in GET /api/v2/runs/get). Any other field, an empty id, a capCents that is not a positive integer or an acceptRemainingCap that is not a boolean is a 400.
When a restart is refused
A409 invalid_state names why the run cannot be restarted in its message:
409 carries error.capHeadroom: { "remainingCents", "capCents", "consumedCents", "estimateCents" }. Restart again with capCents above capCents to raise the cap (the raise is audited), or with acceptRemainingCap: true to restart within what is left. These are the choices the Forge Console’s cap dialog offers.
Who may restart a run
The run is decided at the run’s home: its own org unit when it records one, else its workflow’s owning org unit.- A run you cannot read (
runs:readat its home and at every company it carries) answers404like a missing run. - A run you can read but whose home you do not hold
runs:manageat answers403.
runs:manage at the run’s home, and the run is never restarted twice for that key (see Idempotency).
Related
Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255Body
id is the failed run's id; fromStepId is the graph node to restart from (it and every step after it run again). capCents above the run's cost cap raises the cap to it (audited); acceptRemainingCap: true restarts within the remaining headroom.

