EXEC
Run commands in a pod with live NDJSON streaming.
EXEC
POST /v1/pods/{id}/exec runs a command inside a pod. The response is a NDJSON stream (one JSON object per line) that delivers stdout/stderr live, then a final exit event with the exit code and duration.
REQUEST
Headers: Authorization: Bearer <key>, Content-Type: application/json, Accept: application/x-ndjson (optional; NDJSON is the only response format).
Body:
{
"argv": ["python3", "-c", "print('hello')"],
"timeoutSeconds": 60,
"workdir": "/workspace"
}| Field | Type | Required | Description |
|---|---|---|---|
argv | string[] | yes | Command and arguments. No shell expansion. |
timeoutSeconds | int | no | Override the plan default. Capped at the plan's execTimeoutSeconds. |
workdir | string | no | Working directory. Defaults to /workspace. |
RESPONSE_STREAM
Each line is a JSON object with a type field:
type | Fields | Meaning |
|---|---|---|
stdout | data: string | A chunk of stdout output |
stderr | data: string | A chunk of stderr output |
exit | code: number, durationMs: number | Command finished; code is the process exit code |
error | code: string, message: string | Platform error (timeout, resource limit, engine failure) |
Example stream:
{"type":"stdout","data":"hello"}
{"type":"exit","code":0,"durationMs":142}The HTTP status is 200 for the entire stream — command failure is signalled by the exit.code field, not the HTTP status. Use the stream's final exit event to determine success.
ERRORS_STREAM_LEVEL
If the platform cannot start the exec (pod not running, quota exceeded, timeout exceeded before start), the HTTP status is non-200 and the body is the standard error envelope:
{ "error": { "code": "quota_exceeded", "message": "...", "requestId": "req_...", "docsUrl": "..." } }OUTPUT_SIZE_LIMITS
The engine retains head + tail of the output stream up to the plan's execMaxOutputBytes. When the limit is exceeded, the middle is elided and the stream includes a marker line:
{ "type": "stdout", "data": "...[truncated]..." }