---
title: "Run a cell of Python, JavaScript, TypeScript, R, Java, Bash or Go in a stateful context and return its results."
method: POST
path: "/v1/sandboxes/{id}/interpreter:run"
tags: ["interpreter"]
---

# Run a cell of Python, JavaScript, TypeScript, R, Java, Bash or Go in a stateful context and return its results.

`POST /v1/sandboxes/{id}/interpreter:run`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}/interpreter:run`
- Auth: HTTP bearer

Variables, imports and functions persist between calls to the same context, like a notebook (Go keeps declarations, not values: each Go cell is compiled with the functions, types and imports of earlier cells and run). Returns stdout, stderr, results (a MIME bundle each: text/plain, text/html, image/png as base64, image/svg+xml, text/markdown, application/json, application/vnd.runtime.table+json for a table), and an error with its traceback. matplotlib figures and R plots are returned as PNG images; a pandas DataFrame, an R data frame and a JavaScript array of objects as tables. In every language, `display` returns a file (.png .jpg .svg .html .md .json .txt, .csv as a table) as a result. A value larger than 48 KiB, and output beyond 256 KiB per stream, is written to a file in the sandbox and returned as a ref you can fetch with the result route. Needs the exec, write_file and read_file scopes. python3, node and bash are in the default image. R (r-base-core), Java (openjdk-21-jdk-headless) and Go (golang-go) are installed from the Ubuntu archive on a context's first start when the image lacks them, which takes tens of seconds once and needs the archive allowed by the sandbox's network rules.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `code` string, required: The cell to run.
  - `language` 'python' | 'javascript' | 'typescript' | 'r' | 'java' | 'bash' | 'go': python by default. R, Java and Go are installed on first use (tens of seconds, once) when the image lacks them.
  - `context` string: A context's id; each language's name is its default context, started on first use.
  - `timeoutMs` integer: Interrupt the cell after this long; 0 disables the cell deadline. The sandbox lease still applies. The context survives an interrupt; a cell that ignores it is killed 5 s later with its context.
  - `stream` boolean: Stream events as newline-delimited JSON (application/x-ndjson) while the cell runs, ending with the execution.
  - `interruptOnDisconnect` boolean: Interrupt the cell when the caller disconnects. false detaches the reader and leaves the cell running under the sandbox's lease.

## Response `200`

Success

- object
  - `id` string, required
  - `contextId` string, required
  - `language` 'python' | 'javascript' | 'typescript' | 'r' | 'java' | 'bash' | 'go', required
  - `executionCount` integer, nullable
  - `status` 'ok' | 'error' | 'interrupted' | 'timeout' | 'lost', required
  - `stdout` string, required
  - `stderr` string, required
  - `results` object[], required
    - `main` boolean, required: The cell's own value, rather than a display.
    - `data` object, required: A MIME bundle: text/plain, image/png (base64)...
    - `refs` object, required: Values too large to travel inline: fetch each with the results route.
  - `error` object, nullable, required
    - `name` string
    - `value` string
    - `traceback` string
  - `durationMs` integer

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)