---
title: "Get Single Vm Execution"
method: GET
path: "/v1/vm-executions/{id}"
tags: ["v1"]
---

# Get Single Vm Execution

`GET /v1/vm-executions/{id}`

## Request

- Base URL: `https://api.ellipsis.dev`
- URL: `https://api.ellipsis.dev/v1/vm-executions/{id}`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Headers

- `user-agent` string, nullable

## Response `200`

Successful Response

- VMExecutionResponse
  - `cache_tier` 'exact' | 'incremental' | 'full', required: Which image-cache tier a sandbox creation took — the customer-facing names for `create_sandbox_from_default`'s exact / latest / default tiers. Rides on `Sandbox.cache_tier` and the sandbox_ready lifecycle record.
  - `cost_sandbox_cpu` integer, required
  - `cost_sandbox_memory` integer, required
  - `cpu` number, required
  - `encrypted_ports` integer[], required
  - `environment_variable_keys` string[], required
  - `failed_at` string, date-time, nullable, required
  - `hooks` EnvironmentHooksOutput: Environment lifecycle scripts, in order: build_base, after_checkout, before_start, validate. The first two produce reusable snapshots; before_start runs before an agent starts or resumes its session, and validate runs last to check that the environment has what the agent needs. Scripts run as the environment's user in the workspace directory `/sandbox`. A nonzero exit fails the session. Legacy post_start/post_clone scripts remain supported for existing configs; both run after workspace preparation, before the agent starts or resumes. They cannot be combined with the new lifecycle fields.
    - `after_checkout` union, required: Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared environment. Skipped when that prepared environment is reused.
      - EnvironmentScript: An inline shell script run as the environment's user, with the workspace directory `/sandbox` as cwd.
        - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
      - string
    - `before_start` union, required: Run before the agent starts or resumes a session, after the environment is ready. This hook is not cached and adds to session startup time.
      - EnvironmentScript: An inline shell script run as the environment's user, with the workspace directory `/sandbox` as cwd.
        - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
      - string
    - `build_base` union, required: Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs.
      - EnvironmentBaseBuildOutput: Create a reusable base, optionally using only selected repository files.
        - `inputs` string[], nullable, required: Exact files relative to the workspace directory `/sandbox`, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files.
        - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
      - string
    - `post_clone` string, nullable, required: Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation.
    - `post_start` string, nullable, required: Legacy session startup script. Use before_start in new configurations.
    - `validate` union, required: Check that the environment works, for example that required tools are on PATH. Runs last, after before_start, each time a session starts or resumes and each time the environment is built after a change. A nonzero exit fails the session or the build. Not cached.
      - EnvironmentScript: An inline shell script run as the environment's user, with the workspace directory `/sandbox` as cwd.
        - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
      - string
  - `id` string, required
  - `memory_mib` integer, required
  - `phase_timings` object, required
  - `post_clone` string, nullable, required
  - `post_start` string, nullable, required
  - `repositories` SandboxRepository[], required
    - `id` integer, required
    - `name` string, required
    - `owner_id` integer, required
    - `owner_name` string, required
    - `sha` string, required
  - `running_at` string, date-time, nullable, required
  - `scheduled_at` string, date-time, required
  - `source` 'session' | 'image_refresh' | 'environment_check' | 'test' | 'script', required
  - `source_session_id` string, nullable, required
  - `status` 'scheduled' | 'building' | 'running' | 'released' | 'terminating' | 'terminated' | 'failed', required
  - `terminated_at` string, date-time, nullable, required
  - `terminating_at` string, date-time, nullable, required
  - `timeout_seconds` integer, required
  - `tunnels` SandboxPort[], required
    - `port` integer, required
    - `tcp_host` string, nullable
    - `tcp_port` integer, nullable
    - `tls_host` string, required
    - `tls_port` integer, required
    - `tunnel_url` string, required
    - `unencrypted_host` string, nullable
    - `unencrypted_port` integer, nullable
  - `type` 'claude_code', required
  - `unencrypted_ports` integer[], required

## Other responses

- `401`: The bearer token is missing, invalid, or revoked.
- `403`: The credential may not perform this action, or the account is blocked.
- `422`: Validation Error

---

[API](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api.md) - [All operations](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/revisions/344b16df9a1a?raw)