---
title: "Execs · API reference · Promigence"
description: "The Promigence API's execs routes: 7 in all, with parameters, request bodies and answers."
url: "https://www.promigence.ai/docs/reference/api/execs"
site: "Promigence"
---

[API reference](https://www.promigence.ai/docs/reference/api)

# Execs

7 routes of the published API contract, generated from it.

### GET/v1/execs/{id}

Auth: API key

One exec by id alone, without knowing its sandbox or run. An exec belonging to another org is a 404, never a 403. A background command's id (`x_…`) answers as `GET /v1/sandboxes/:id/execs/:exec_id` does, with the same `?stream`, `?offset`, `?len` and `?wait_ms`; after a restart of the service that id is found only through its sandbox.

#### Parameters

idrequiredpath · string

lenquery · integer

offsetquery · integer

streamquery · string

untilquery · string

wait_msquery · integer

#### Answer 200 · ExecView · application/json

argvrequiredstring[]

The command, as it was run.

cpu_msrequirednumber

cwdstring | null

The working directory it ran in.

env_keysrequiredstring[]

The names of the environment variables it was given. Never the values.

exec_idrequiredstring

exit_codeinteger | null

`null` while it is still running, or if a signal killed it.

max_rss_kibrequiredinteger

Peak resident memory, in kibibytes.

run_idrequiredstring

sandbox_idrequiredstring

signalinteger | null

The signal that killed it, if one did.

started_atrequiredstring

When it started, RFC 3339.

stderrrequiredstring

stdoutrequiredstring

terminalrequiredboolean

True when this command owned the sandbox: the sandbox ends when the command does.

truncatedrequiredboolean

True when the output was cut: at the request's byte limit, or, in a sandbox's `execs`, to the last 64 KiB of each stream. `GET /v1/execs/{id}` returns the whole recorded output.

wall_msrequirednumber

### GET/v1/sandboxes/{id}/execs

Auth: API key

List this sandbox's background execs.

#### Parameters

idrequiredpath · string

#### Answer 200 · BackgroundExecList · application/json

execsrequiredBackgroundExec[]

sandbox_idrequiredstring

### POST/v1/sandboxes/{id}/execs

Auth: API key

Run a command. Buffered by default; `Accept: text/event-stream` streams it; `background: true` returns 202 with a handle instead of waiting. A sandbox parked by its `auto_pause_s` rule is woken first; one paused with `POST …/pause` is not, and answers that it is paused. `max_output_bytes` (default 64 KiB) is per stream and at most 32 MiB; output past it is cut and the reply says `truncated: true`.

#### Parameters

idrequiredpath · string

Idempotency-Keyheader · string

Optional. Makes a retried command safe: send the same key on every attempt of ONE command and it runs once. Kept 24 hours per org. The same key with the same request answers with the first answer (same `exec_id`), marked `Idempotent-Replayed: true`; the same key with a different request is refused with 409 `idempotency_key_reused`. Honoured on a buffered or background command; a streamed one (`Accept: text/event-stream`) refuses a key. At most 1 MiB of output is kept for a replay: a replay of a longer answer is cut and says so with `replay_truncated: true`. Nothing is kept unless you send a key; the SDKs send one only when you pass it.

#### Request body ExecCreate · application/json · optional

argvstring[] | null

The program and its arguments, run without a shell.

backgroundboolean

Answer at once (202) with a handle to poll, instead of waiting for the command.

cwdstring | null

The working directory. Defaults to the snapshot's workspace.

encodingstring | null

`text` (the default) or `base64`: the answer's output as `stdout_b64` / `stderr_b64`, the exact bytes, for output that is not text (an archive, an image). The buffered answer only.

envmap of string

Extra environment variables.

followboolean

With `background`: the command is read as it runs, by a caller that may lose its connection and come back. The newest `max_output_bytes` of each stream are kept (8 MiB by default; older bytes are dropped, and a read that asks for them says how many in `skipped`), and the handle is freed 10 minutes after the command ends, read or not. The command never stops because a caller went away.

kill_on_exitboolean | null

End the sandbox when the command exits (default: the value of `terminal`).

max_output_bytesinteger | null

Output kept per stream, in bytes (default 64 KiB, 1 MiB for a background exec; max 32 MiB).

secretsSecretUse[]

Stored secrets the command receives as environment variables.

shstring | null

A line for `sh -c`.

stdinboolean

Keep the command's stdin open for `POST …/execs/{exec_id}/stdin` (background execs).

terminalboolean

The sandbox ends when this command exits.

timeout_msinteger | null

Milliseconds before the command is ended. A positive integer; omitted, 15 minutes.

userstring | null

The user to run as.

#### Answer 200 · ExecResult · application/json

cpu_msnumber | null

exec_idrequiredstring

exit_codeinteger | null

`null` if a signal killed the command.

oom_killedboolean

Present (true) when the command was killed for running out of memory.

reasonstring | null

Why the command ended without an exit code: `timeout`, `out_of_memory` or `signal`. Absent when it exited on its own.

sandbox_idrequiredstring

signalinteger | null

The signal that killed it, if one did.

stderrstring | null

stderr_b64string | null

With `encoding: "base64"`: the exact bytes of standard error, base64.

stdoutstring | null

stdout_b64string | null

With `encoding: "base64"`: the exact bytes of standard output, base64 (`stdout` is then empty). Bytes that are not UTF-8 survive here; as text they become U+FFFD.

timed_outboolean

Present (true) when the command was killed at its own `timeout_ms`.

truncatedrequiredboolean

True when the output was cut at the request's byte limit.

wall_msnumber | null

### GET/v1/sandboxes/{id}/execs/{exec_id}

Auth: API key

Read a background exec. `?stream=stdout|stderr&offset=&len=` takes a byte range; `?wait_ms=N` parks until it exits.

#### Parameters

idrequiredpath · string

exec_idrequiredpath · string

lenquery · integer

offsetquery · integer

streamquery · string

untilquery · string

wait_msquery · integer

#### Answer 200 · BackgroundExec · application/json

argvstring | null

The command, as one line.

backgroundrequiredboolean

Always true: this is the handle form of a command.

datastring | null

The bytes, base64.

eofboolean | null

True when `data` reaches the end of what is held so far.

errorBackgroundExecError | null

Why the command could not run; only when `state` is `failed`.

exec_idrequiredstring

exitBackgroundExecExit | null

How the command ended; only once `state` is `exited`.

followboolean | null

Started with `follow`: the newest output is kept, and the handle is freed 10 minutes after the command ends.

idle_hold_sinteger | null

Present when the sandbox pauses itself when idle: after this command ends, the idle rule waits up to this many seconds for its result to be read before it pauses the sandbox (a pause drops the handle and its output). Reading its output once it has finished releases the hold, and so does deleting the handle (`DELETE /v1/sandboxes/{id}/execs/{exec_id}`, CLI `exec kill EXEC --forget`).

idle_hold_untilstring | null

When this finished command stops holding the idle rule off (RFC 3339), while it still does: absent for a running command, once its output has been read, and once the time has passed.

leninteger | null

Bytes in `data`.

offsetinteger | null

sandbox_idrequiredstring

skippedinteger | null

A `follow` command only: bytes between the `offset` asked for and the first byte still held, dropped to keep the newest output; `data` then starts at `offset + skipped`.

started_unix_nsinteger | null

Unix nanoseconds.

staterequiredstring

`running` | `exited` | `failed`.

stderr_bytesinteger | null

stderr_totalinteger | null

stdin_openboolean | null

True while the command's standard input can still be written to.

stdout_bytesinteger | null

Bytes of standard output held and readable by range.

stdout_totalinteger | null

Bytes of standard output the command has written in total.

streaminteger | null

Which stream `data` is from: 1 for stdout, 2 for stderr.

truncatedboolean | null

True when more was written than is held.

waited_msinteger | null

How long a `?wait_ms=` read waited, in milliseconds.

### DELETE/v1/sandboxes/{id}/execs/{exec_id}

Auth: API key

SIGKILL the background exec and drop its handle and buffered output.

#### Parameters

idrequiredpath · string

exec_idrequiredpath · string

#### Answer 200 · ExecForgotten · application/json

exec_idrequiredstring

forgottenrequiredboolean

okrequiredboolean

sandbox_idrequiredstring

### POST/v1/sandboxes/{id}/execs/{exec_id}/signal

Auth: API key

Signal a background exec.

#### Parameters

idrequiredpath · string

exec_idrequiredpath · string

#### Request body ExecSignal · application/json · optional

signalNumberOrName | null

A signal number 1–64, or a name such as `SIGTERM` or `TERM`. Default 15 (SIGTERM).

#### Answer 200 · ExecSignalled · application/json

already_endedboolean | null

Present, and true, only when the command had already finished.

deliveredrequiredboolean

False when the command had already finished, which is not a failure: the process is gone, which is what a kill wanted.

exec_idrequiredstring

okrequiredboolean

sandbox_idrequiredstring

signalrequiredinteger

The signal that was sent, as a number.

### POST/v1/sandboxes/{id}/execs/{exec_id}/stdin

Auth: API key

Write to a running command's standard input, and close it. `data` is base64 — stdin is bytes, and a JSON string cannot carry all of them. Send `data` and `eof` together for the common "write this and close". The command must have been started with `stdin: true`; a process already running on `/dev/null` cannot be handed an input later, so writing to one is an error rather than a write that goes nowhere.

#### Parameters

idrequiredpath · string

exec_idrequiredpath · string

#### Request body ExecStdin · application/json · optional

datastring | null

Bytes to write, base64.

eofboolean

Close stdin after this write.

#### Answer 200 · StdinAck · application/json

eofrequiredboolean

This call closed the input side.

exec_idrequiredstring

okrequiredboolean

sandbox_idrequiredstring

writtenrequiredinteger

Bytes handed to the child's stdin by this call.

[Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)