Executions

The Executions API lets you run commands and tools inside a sandbox session. Each execution captures the command or tool invocation along with its output, exit code, and timing information.

---

List Executions

Retrieve all executions for a given sandbox session.

Endpoint

GET https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/executions

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID

Status Codes

Code	Description
200	Returns array of executions
401	Unauthorized — invalid or missing credentials
404	Session not found

Response Body

Returns an array of execution objects. See execution fields below.

Example Responses

200 OK

{
  "data": [
    {
      "id": "eX7kP2",
      "command": "ls -la /mnt/session/repos",
      "tool_name": null,
      "tool_input": null,
      "stdout": "total 4\ndrwxr-xr-x 3 root root 4096 Jun 01 10:00 api-server\n",
      "stderr": "",
      "exit_code": 0,
      "started_at": "2026-06-01T10:10:00Z",
      "completed_at": "2026-06-01T10:10:01Z",
      "created_at": "2026-06-01T10:10:00Z"
    }
  ]
}

---

Create Execution

Run a shell command or invoke a tool inside a sandbox session. At least one of command or tool_name should be provided.

Endpoint

POST https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/executions

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Content-Type	application/json
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID

Request Body

Field	Type	Required	Description
command	string	No	Shell command to execute
tool_name	string	No	Name of the tool to run
tool_input	object	No	Input parameters for the tool

Example — Shell command

{
  "command": "ls -la /mnt/session/repos"
}

Example — Tool invocation

{
  "tool_name": "file_search",
  "tool_input": {
    "query": "database connection",
    "path": "/mnt/session/repos/api-server"
  }
}

Status Codes

Code	Description
201	Execution created
401	Unauthorized — invalid or missing credentials
404	Session not found
422	Validation error

Response Body

See execution fields below.

Example Responses

201 Created

{
  "data": {
    "id": "eX7kP2",
    "command": "ls -la /mnt/session/repos",
    "tool_name": null,
    "tool_input": null,
    "stdout": "total 4\ndrwxr-xr-x 3 root root 4096 Jun 01 10:00 api-server\n",
    "stderr": "",
    "exit_code": 0,
    "started_at": "2026-06-01T10:10:00Z",
    "completed_at": "2026-06-01T10:10:01Z",
    "created_at": "2026-06-01T10:10:00Z"
  }
}

422 Unprocessable Entity

{
  "errors": [
    {
      "code": "validation_error",
      "message": "Either command or tool_name must be provided"
    }
  ]
}

---

Get Execution

Retrieve a specific execution by ID.

Endpoint

GET https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/executions/{execId}

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID
execId	string (hashid)	Yes	The execution ID

Status Codes

Code	Description
200	Returns the execution
401	Unauthorized — invalid or missing credentials
404	Session or execution not found

Response Body

Field	Type	Description
id	string (hashid)	Unique identifier for the execution
command	string or null	Shell command that was executed
tool_name	string or null	Name of the tool that was invoked
tool_input	object or null	Input parameters passed to the tool
stdout	string or null	Standard output from the execution
stderr	string or null	Standard error from the execution
exit_code	integer or null	Process exit code (0 indicates success)
started_at	string (ISO 8601)	When the execution started
completed_at	string (ISO 8601) or null	When the execution finished
created_at	string (ISO 8601)	When the execution record was created

Example Responses

200 OK

{
  "data": {
    "id": "eX7kP2",
    "command": "ls -la /mnt/session/repos",
    "tool_name": null,
    "tool_input": null,
    "stdout": "total 4\ndrwxr-xr-x 3 root root 4096 Jun 01 10:00 api-server\n",
    "stderr": "",
    "exit_code": 0,
    "started_at": "2026-06-01T10:10:00Z",
    "completed_at": "2026-06-01T10:10:01Z",
    "created_at": "2026-06-01T10:10:00Z"
  }
}

404 Not Found

{
  "errors": [
    {
      "code": "not_found",
      "message": "Execution not found"
    }
  ]
}