---
title: "Returns a collection of SandboxEngines within a workspace."
method: GET
path: "/v1/{parent}/sandboxEngines"
tags: ["SandboxEngineService"]
---

# Returns a collection of SandboxEngines within a workspace.

`GET /v1/{parent}/sandboxEngines`

## Request

- Base URL: `https://docs.h2o.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.h2o.ai/v1/{parent}/sandboxEngines`
- Auth: none declared
- TypeScript: <https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/docs/v1/:parent/sandboxEngines/get.ts> (a function with typed inputs; its response is checked against the schema)

Authorization may require the following permission on the engine's parent workspace:
* actions/enginemanager/sandboxEngines/LIST

## Path parameters

- `parent` string, required

## Query parameters

- `pageSize` integer
- `pageToken` string

## Response `200`

A successful response.

- V1ListSandboxEnginesResponse: Response message for SandboxEngineService.ListSandboxEngines.
  - `sandboxEngines` V1SandboxEngine[]: Collection of SandboxEngines.
    - `name` string: Identifier. SandboxEngine resource name.
    - `displayName` string: Optional. Human-readable name of the SandboxEngine. Must contain at most 63 characters. Does not have to be unique.
    - `uid` string: Output only. Globally unique identifier of the resource.
    - `state` 'STATE_UNSPECIFIED' | 'STATE_STARTING' | 'STATE_RUNNING' | 'STATE_TERMINATING' | 'STATE_TERMINATED' | 'STATE_FAILED' | 'STATE_DELETING': All possible SandboxEngine states. - STATE_UNSPECIFIED: SandboxEngine state is unspecified or unknown. - STATE_STARTING: SandboxEngine is starting. - STATE_RUNNING: SandboxEngine is running. - STATE_TERMINATING: SandboxEngine is terminating. - STATE_TERMINATED: SandboxEngine is terminated. - STATE_FAILED: SandboxEngine has failed. - STATE_DELETING: SandboxEngine is being deleted.
    - `creator` string: Output only. Name of an entity that created the SandboxEngine.
    - `creatorDisplayName` string: Output only. Human-readable name of creator.
    - `createTime` string, date-time: Output only. Time when the SandboxEngine creation was requested.
    - `sandboxEngineImage` string, required: Required. Immutable. The resource name of the SandboxEngineImage that is assigned to this SandboxEngine. Format is `workspaces/*/sandboxEngineImages/*`.
    - `sandboxEngineImageInfo` V1SandboxEngineImageInfo: The original SandboxEngineImage data used by SandboxEngine when using the SandboxEngineImage. For more info about each field see the original SandboxEngineImage resource.
      - `image` string
      - `name` string
      - `displayName` string
      - `enabled` boolean
      - `imagePullPolicy` 'IMAGE_PULL_POLICY_UNSPECIFIED' | 'IMAGE_PULL_POLICY_ALWAYS' | 'IMAGE_PULL_POLICY_NEVER' | 'IMAGE_PULL_POLICY_IF_NOT_PRESENT': Policy for downloading an image in K8s. - IMAGE_PULL_POLICY_UNSPECIFIED: Unspecified image pull policy. - IMAGE_PULL_POLICY_ALWAYS: Every time the container is launched, the container image registry is queried to resolve the name to an image digest. - IMAGE_PULL_POLICY_NEVER: Do not try to fetch the image. If the image is already present locally, the container will start. If the image is not present, container startup will fail. - IMAGE_PULL_POLICY_IF_NOT_PRESENT: The image is pulled only if it is not already present locally.
      - `imagePullSecrets` string[]
      - `createTime` string, date-time
      - `updateTime` string, date-time, nullable
      - `creator` string
      - `updater` string
      - `creatorDisplayName` string
      - `updaterDisplayName` string
    - `sandboxEngineTemplate` string, required: Required. Immutable. The resource name of the SandboxEngineTemplate that is assigned to this SandboxEngine. Format is `workspaces/*/sandboxEngineTemplates/*`.
    - `sandboxEngineTemplateInfo` V1SandboxEngineTemplateInfo: The original SandboxEngineTemplate data used by SandboxEngine when using the SandboxEngineTemplate. For more info about each field see the original SandboxEngineTemplate resource.
      - `name` string
      - `displayName` string
      - `milliCpuRequest` integer
      - `milliCpuLimit` integer
      - `gpuResource` string
      - `gpu` integer
      - `memoryBytesRequest` string, int64
      - `memoryBytesLimit` string, int64
      - `storageBytes` string, int64
      - `storageClassName` string
      - `environmentalVariables` object
      - `yamlPodTemplateSpec` string
      - `enabled` boolean
      - `maxIdleDuration` string
      - `createTime` string, date-time
      - `updateTime` string, date-time, nullable
      - `creator` string
      - `updater` string
      - `creatorDisplayName` string
      - `updaterDisplayName` string
      - `maxRunningDuration` string
    - `currentIdleDuration` string, nullable: Output only. Current time the SandboxEngine is idle.
    - `annotations` object: Optional. Additional arbitrary metadata associated with the SandboxEngine. Annotations are key/value pairs. The key must: - be 63 characters or less - begin and end with an alphanumeric character ([a-z0-9A-Z]) - with dashes (-), underscores (_), dots (.), and alphanumerics between - regex used for validation is: ^[A-Za-z0-9]([-A-Za-z0-9_.]{0,61}[A-Za-z0-9])?$
    - `pendingReason` 'PENDING_REASON_UNSPECIFIED' | 'PENDING_REASON_CREATING_RESOURCES' | 'PENDING_REASON_SCHEDULING' | 'PENDING_REASON_PULLING_IMAGE' | 'PENDING_REASON_CONTAINER_CREATING' | 'PENDING_REASON_WAITING_READINESS' | 'PENDING_REASON_DELETING_RESOURCES': All possible reasons why a SandboxEngine is in a pending/waiting state. - PENDING_REASON_UNSPECIFIED: No pending reason - engine is in a stable state (RUNNING, TERMINATED, FAILED). - PENDING_REASON_CREATING_RESOURCES: Kubernetes resources (Pod, Service) are being created. - PENDING_REASON_SCHEDULING: Pod is waiting to be scheduled to a node. - PENDING_REASON_PULLING_IMAGE: Node is pulling the container image. - PENDING_REASON_CONTAINER_CREATING: Container is being created (init containers, volumes, network setup). - PENDING_REASON_WAITING_READINESS: Container is running but application is not ready yet. - PENDING_REASON_DELETING_RESOURCES: Kubernetes resources are being cleaned up.
    - `pendingMessage` string: Output only. Human-readable message providing details about the current pending state. Contains information from Kubernetes about what the engine is waiting for. Empty when the engine is in a stable state.
  - `nextPageToken` string: Used to retrieve the next page of results. When unset, no further items are available (this response was the last page).

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto.md) - [All operations](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/revisions/297cfadc1d39?raw)