Create agent run
POST/api/agents/:agent_id/runs
Execute an agent run. By default, set stream to true to receive server-sent events; otherwise the response contains the final agent messages. Set execution_mode to DURABLE to persist a new run and return its initial snapshot with HTTP 201 without waiting for execution. Poll the agent-scoped GET run endpoint for progress. Durable execution continues after an HTTP disconnect, but is not automatically resumed after a QE restart or crash. An active turn becomes overdue more than 40 minutes after acceptance (a 30-minute execution timeout plus 10 minutes of grace). The next GET of the run marks the overdue turn FAILED without replay; there is no periodic sweep. Without a GET, the stored run can remain RUNNING. Failure does not prove that external tool work has stopped. Paused runs are not expired; an accepted approval continuation starts a fresh deadline. Each POST creates a new run; retrying a POST can create another execution. Submit pending approval decisions through the run responses endpoint, and cancellation can be requested through the run cancellations endpoint. A run tracks one workflow execution; automatic background-subagent wake turns are separate executions, not continuations tracked by this run ID.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 404
- 408
- 409
- 413
- 422
- 429
- 500
- 503
Successful response.
Durable run persisted and started. The snapshot is immediately retrievable through GET /api/agents/{agent_id}/runs/{run_id}. Execution failures appear in the run state.
Invalid request (malformed JSON, invalid parameter values, unknown fields).
Missing or invalid authentication token.
Token valid but lacks permission for the requested operation.
Resource not found.
Backend did not respond within the timeout window.
Request conflicts with current state of the resource.
Request body exceeds the maximum allowed size.
Returned when the agent has tools the caller must authorize before the run can start. authentication_suggestions names each such tool; POST its server_id to the Client API's /tool-servers/{serverId}/auth with returnUrl in the request body to obtain an authorizationUrl to redirect the end user to, then retry the run once OAuth completes.
Rate limit exceeded. Includes Retry-After header.
Unexpected server-side failure.
Backend temporarily unavailable.