Create Run
http
POST /api/v1/sessions/{sid}/runsCreate a subsequent run. Sessions created with allow_multiple_runs=false reject this operation with 409 multiple_runs_not_allowed. Deleting, deleted or unavailable environments reject new input with 409 session_unavailable; create a new session with the required context. If external sandbox loss is discovered after acceptance, the run fails asynchronously with sandbox_lost. Idempotent replay of an accepted request returns the original acceptance, regardless of sandbox state.
operationId: create_run
Authentication
HTTPBearer
See browser access. Session mutations require a Bearer key.
Parameters
| Name | In | Required | Type | Description and constraints |
|---|---|---|---|---|
sid | path | Yes | string | format: "uuid" |
Idempotency-Key | header | No | string / null |
Request body
application/json: CreateRun
json
{
"$ref": "#/components/schemas/CreateRun"
}Responses
| Code | Description | Content |
|---|---|---|
| 202 | Successful Response | application/json: Accepted |
| 400 | Bad Request | application/json: ErrorResponse |
| 401 | Unauthorized | application/json: ErrorResponse |
| 403 | Browser sessions allow reading only (read_only_access). | application/json: ErrorResponse |
| 404 | Not Found | application/json: ErrorResponse |
| 409 | Conflict | application/json: ErrorResponse |
| 413 | Content Too Large | application/json: ErrorResponse |
| 415 | Unsupported Media Type | application/json: ErrorResponse |
| 422 | Unprocessable Content | application/json: ErrorResponse |
| 503 | Service Unavailable | application/json: ErrorResponse |
Response headers 202
Location: URL of the accepted run. string