Skip to main content
POST
Start Run

Start Run

Starts a new run for an existing work order. This is useful for retrying failed work orders or re-running successful ones.
The work order must be in queued or failed status to start a new run. Running or completed work orders cannot have new runs started.

Request

id
string
required
The work order ID (e.g., wo_abc123)

Response

success
boolean
required
Indicates if the request was successful
data
object
required
Run information

Example Response

Error Responses

Work Order Not Found

Invalid Status

Returns 409 Conflict if the work order is not in a runnable state.

Insufficient Credits

Returns 402 Payment Required if credits are insufficient.

Status Requirements

Use Cases

Retry a Failed Work Order

Monitor the New Run

After starting a run, you can monitor its progress:

Run Lifecycle

When you start a run:
  1. Request received - Run ID is generated
  2. Status: queued - Run is queued for execution
  3. Status: building - Workspace is being prepared
  4. Status: running - Agent is executing
  5. Status: succeeded/failed - Run completes
The response returns immediately with the run ID. The run executes asynchronously.
Use WebSocket streaming or polling to monitor run progress in real-time.