Skip to main content
POST
Restart a failed run from a step
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

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

A 409 invalid_state names why the run cannot be restarted in its message: When the run carries a cost cap and the restarted step’s estimate does not fit in what is left, the 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:read at its home and at every company it carries) answers 404 like a missing run.
  • A run you can read but whose home you do not hold runs:manage at answers 403.
A Personal key acts with its owner’s permissions narrowed by its scopes. A Forge agent may restart a run when its grants say so. The restart is recorded as your key’s or app’s principal, never a person. A same-key retry returns the recorded answer only while you still hold runs:manage at the run’s home, and the run is never restarted twice for that key (see Idempotency).

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255

Path Parameters

runId
string
required
Minimum string length: 1

Body

application/json

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.

fromStepId
string
required
Minimum string length: 1
capCents
integer
acceptRemainingCap
boolean

Response

The run restarted as a new attempt

data
object
required

The run restarted as a new attempt of the same run: status is running; poll GET /api/v2/runs/get for its progress.

meta
object
required