API reference · Sandboxes
Run code in the sandbox and wait for the result (or stream it)
/v1/sandboxes/{sandbox_id}/runs- TypeScript
client.sandboxes.runCode()- Python
client.sandboxes.run_code()- CLI
hayonix sandboxes run
Python runs share one interpreter per sandbox, so variables, imports and functions persist between runs; JavaScript and shell runs each start a fresh process. Files in the workspace persist for the sandbox’s life whatever the language. A run started right after the sandbox was created waits for it to be ready. By default the call answers once the run has finished, with all of its output (up to its cap); wait=false answers at once with the queued run (follow it with GET …/runs/{run_id}/events), and stream=true answers with that event stream directly. A retry with the same Idempotency-Key never runs the code twice.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the sandbox:update permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/sandboxes/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"language": "python",
"code": "x = 21 * 2\nprint(x)",
"timeout_seconds": 30
}'Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Path parameters
sandbox_idstringrequiredID of the sandbox
ID with prefix sbx_
Query parameters
waitboolean | stringtrue (default): answer when the run has finished. false: answer at once with the queued run; follow it with GET …/runs/{run_id}/events
streamboolean | stringtrue: answer with the run’s events as a server-sent event stream (the same events as GET …/runs/{run_id}/events)
Body
JSON (application/json): RunCodeRequest.
languagestringrequiredpython (one interpreter per sandbox: state persists between runs), javascript (Node, a fresh process per run) or shell (bash, a fresh process per run)
One of
pythonjavascriptshellcodestringrequiredMachine-readable code
stdinstringGiven to the code on standard input
timeout_secondsintegerTime limit (default 60)
1–900
max_output_bytesintegerstdout + stderr cap; the run is cut off past it (default 1048576)
1024–4194304
Response
201 SandboxRun — The run (finished, unless wait=false), or its events with stream=true
objectstringrequiredAlways `sandbox_run`: the type of this object
One of
sandbox_runidstringrequiredUnique ID (`sbr_…`)
ID with prefix sbr_
sandbox_idstringrequiredID of the sandbox
ID with prefix sbx_
languagestringrequiredLanguage the code ran as
One of
pythonjavascriptshellstatestringrequiredqueued | running | completed (it ran: see exit_code and cut_off) | error (it could not run: see error)
One of
queuedrunningcompletederroroutcomestring | nullrequiredOne word for how it ended (null while queued or running)
One of
succeededfailedtime_limitoutput_limitout_of_memorycancelledsandbox_endederrorexit_codeinteger | nullrequiredExit status of the code (0 means success); null until it finishes, or when it could not run
cut_offstring | nullrequiredWhy it was stopped before it finished: time_limit | output_limit | out_of_memory | cancelled | sandbox_ended
One of
time_limitoutput_limitout_of_memorycancelledsandbox_endedstate_resetbooleanrequiredThe Python interpreter had to be restarted: variables from earlier runs are gone
errorstring | nullrequiredWhy the run could not run or was stopped, for people; null otherwise
stdoutstringrequiredStandard output (see `output.truncated`)
stderrstringrequiredStandard error (see `output.truncated`)
outputobjectrequiredHow much output the run produced
ShowHide 3 fields of
outputstdout_bytesintegerrequiredBytes the run wrote to standard output
stderr_bytesintegerrequiredBytes the run wrote to standard error
truncatedbooleanrequiredstdout and stderr above are the run's whole output (up to its cap) in the response to the run itself, and the first 65536 bytes of each in the record kept for 7 days after the sandbox ends; true when this copy is shorter than what the run produced
codestringrequiredMachine-readable code
timeout_secondsintegerrequiredTime limit the run had, in seconds
max_output_bytesintegerrequiredCap on stdout plus stderr the run had, in bytes
duration_msinteger | nullrequiredHow long it ran, in milliseconds; null until it finishes
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
started_atstring (date-time) | nullrequiredWhen it started (null until then) (ISO 8601, UTC)
finished_atstring (date-time) | nullrequiredWhen it finished (null until then) (ISO 8601, UTC)
Example response
{
"object": "sandbox_run",
"id": "sbr_01jc5zq4m8k3v6x9t2w7r0b1e4",
"sandbox_id": "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4",
"language": "python",
"state": "queued",
"outcome": "succeeded",
"exit_code": 1,
"cut_off": "time_limit",
"state_reset": true,
"error": "string",
"stdout": "string",
"stderr": "string",
"output": {
"stdout_bytes": 1,
"stderr_bytes": 1,
"truncated": true
},
"code": "string",
"timeout_seconds": 1,
"max_output_bytes": 1,
"duration_ms": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"finished_at": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
409 | conflict_error | The resource's current state does not allow this. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |