Get sandbox

Returns one sandbox: its class, project, image, the runtime it was given, its status and when its lease ends.

GET /v1/sandbox/{id}

Sandbox → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/sandbox/{id}`
Method	`GET`
Operation	`get_sandbox_by_id`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns one sandbox: its class, project, image, the runtime it was given, its status and when its lease ends.

An id the caller's org does not hold is the same 404 an unknown id gives — the store is keyed on the org, so a cross-tenant id simply is not there.

Request

1 field.

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the sandbox to address, from the path.

Response

Status	Body	Meaning
`200`	Sandbox	ok

200 body — 14 fields.

Field	In	Type	Always	Description
`class`	body	string	—	Class is what the sandbox is FOR, and it decides the image, the working directory and the isolation: "exec" for a code-interpreter call (workdir /mnt/data, no…
`connectedAt`	body	integer	—	ConnectedAt is when somebody was last known to have this sandbox's project OPEN, Unix seconds.
`createdAt`	body	integer	—	CreatedAt is when the lease was first taken, Unix seconds.
`error`	body	string	—	Error is why the sandbox could not come up, in plain words.
`expiresAt`	body	integer	—	ExpiresAt is when the lease ends, Unix seconds.
`id`	body	string	—	ID is the sandbox's server-minted handle and what every operation addresses it by.
`image`	body	string	—	Image is the container image this sandbox is actually running — the one the class chose, or an override the policy admitted.
`kind`	body	string	—	Kind is the resource family this row belongs to.
`lastUsedAt`	body	integer	—	LastUsedAt is when the sandbox last did work, Unix seconds.
`org`	body	string	—	Org is the org that holds the lease — the validated caller's, never a value a request supplied.
`project`	body	string	—	Project is the project this sandbox is bound to.
`runtime`	body	string	—	Runtime is the isolation boundary this sandbox GOT, which is not always the one it asked for: a caller states a preference and runtimeFor answers with what the…
`status`	body	string	—	Status is where the sandbox is in its life: "pending" while the pod is coming up, "running" once it can take work, "error" when it cannot.
`volume`	body	string	—	Volume is the persistent volume attached to the sandbox, when it has one.

Failure carries the platform error shape — see Errors.

Examples

hanzo sandbox get <id>

import { Configuration, SandboxApi } from 'hanzoai';

const api = new SandboxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getSandboxById({ id: 'id' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import SandboxApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = SandboxApi(client).get_sandbox_by_id(id='id')

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.SandboxAPI.GetSandboxById(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, sandbox_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = sandbox_api::get_sandbox_by_id(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SandboxApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new SandboxApi(client).getSandboxById();

curl https://api.hanzo.ai/v1/sandbox/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches sandbox through the sandboxes tool, which names its 19 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_sandboxes"
         }
       }
     }'

Sandbox API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page