---
title: "List Instances"
method: GET
path: "/compute/v2/thr3/workspaces/{workspaceUUID}/instances"
tags: ["Compute"]
---

# List Instances

`GET /compute/v2/thr3/workspaces/{workspaceUUID}/instances`

Retrieves a paginated list of all compute instances in the specified workspace. 
The response includes details about each instance such as its configuration, 
status, and metadata. Results can be filtered using query parameters.

## Path parameters

- `workspaceUUID` string, required

## Response `200`

Successfully retrieved the list of compute instances. The response includes
basic instance information like name, creation time, specs, and current status.

- Anonymous0e3cbd18
  - `apiVersion` string, required — Version identifier of the API schema
  - `items` Anonymousd9e93299, required — Collection of Instance resources
    - `apiVersion` 'compute/v2', required — Version identifier of the API schema
    - `kind` 'Instance', required — The string value 'Instance' that identifies the schema
    - `metadata` Anonymousaa7ac512, required — Standard resource metadata fields
      - `annotations` object, required — Annotations are key-value pairs storing additional metadata about resources
      - `creationTimestamp` string, date-time, required
      - `deletionTimestamp` string, date-time, required
      - `labels` object, required — Labels are key-value pairs attached to resources for organization and categorization
      - `name` string, required — User-provided name that uniquely identifies the resource within its workspace and type
      - `ownerReferences` Anonymous6efd6cb9, required — References to other resources that own or manage the resource
        - `apiVersion` string, required
        - `blockOwnerDeletion` boolean, nullable
        - `controller` boolean, nullable
        - `kind` string, required
        - `name` string, required
        - `uid` string, required
      - `resourceVersion` string — An opaque value representing the internal version of this object that can be used for optimistic concurrency and change detection
      - `uid` string, required — System-generated unique identifier for the resource
      - `workspace` string, required — Unique identifier of the workspace where the resource belongs
    - `spec` Anonymousf98c6805, required — Desired configuration and characteristics for the instance
      - `iamEnabled` boolean — When enabled, SSH access to this instance will be authenticated through Sotoon IAM.
      - `imageSource` Anonymousaa160065, required — Specifies the base operating system image used to boot the instance. Must specify either an image or customImage, but not both.
        - `customImage` string — Name of the custom image to boot the instance from. Must be a valid custom image name. Cannot be modified after instance creation. Cannot be used together with image.
        - `image` string — Name of the base operating system image to boot the instance from. Must be a valid image name. Cannot be modified after instance creation. Cannot be used together with customImage.
      - `initialUser` Anonymous05e51a84, nullable — Defines the initial OS login credentials. If specified, both username and password must be provided.
        - `password` Anonymous7d0f7a1e, required — Password configuration for the user account, specified either through a secret or file source
          - `fromSecret` Anonymouse785c8dc — Reference to a secret containing the password value. The secret must exist in the same namespace as the instance.
            - `key` string — Key within the secret containing the desired value. If not specified, defaults to the instance name
            - `name` string — Name of the secret in the instance's namespace. If not specified, defaults to <Instance.Name>-login. Must be 1-220 characters long and contain only lowercase alphanumeric characters, - and .
            - `optional` boolean, nullable — When true, the referenced secret and key are optional and will be filled automatically. When false or unset, they must exist
        - `sshAuthorizedKeys` string[] — List of SSH public keys to authorize for this user account
        - `username` string, required — Operating system username for the initial user account. Must follow Linux username requirements.
      - `interfaces` Anonymous5cc7c86e — List of network interfaces to attach to the instance. Each interface defines network connectivity.
        - `link` string, required — Name of the Link resource that defines the network this interface connects to
        - `name` string, required — Unique identifier for this network interface within the instance
      - `osVolume` Anonymousc90cbf69 — Defines the storage volume containing the operating system. Must specify either persistentVolumeClaim or localDisk (localDisk settings are ignored).
        - `localDisk` Anonymousf86d64f7, nullable — Specification for a local disk volume to create and attach to the instance. Cannot be used together with persistentVolumeClaim.
          - `name` string, required — Name of the local disk. This field is automatically populated based on the instance type configuration and should not be set by users.
          - `size` string, string, required
        - `persistentVolumeClaim` Anonymousa57259ba, nullable — Reference to a PersistentVolumeClaim to use as a volume source. Cannot be used together with localDisk.
          - `claimName` string, required
          - `readOnly` boolean
      - `placementGroupRef` Anonymous3fd4cf92, nullable — Reference to a placement group that influences instance scheduling for anti-affinity.
        - `name` string
      - `poweredOn` boolean, required — Controls the power state of the instance. True means the instance is powered on, false means powered off.
      - `restartedAt` string, date-time
      - `type` string, required — Specifies the instance type that determines CPU, memory and other resource allocations. Must match an existing Instance Type name. Can be modified to resize the instance.
      - `userData` string — Cloud-init configuration data provided in base64 encoded format. Used to customize instance on first boot.
      - `volumes` Anonymousc90cbf69 — Defines the storage volume containing the operating system. Must specify either persistentVolumeClaim or localDisk (localDisk settings are ignored).
        - `localDisk` Anonymousf86d64f7, nullable — Specification for a local disk volume to create and attach to the instance. Cannot be used together with persistentVolumeClaim.
          - `name` string, required — Name of the local disk. This field is automatically populated based on the instance type configuration and should not be set by users.
          - `size` string, string, required
        - `persistentVolumeClaim` Anonymousa57259ba, nullable — Reference to a PersistentVolumeClaim to use as a volume source. Cannot be used together with localDisk.
          - `claimName` string, required
          - `readOnly` boolean
    - `status` Anonymousd0ba8611, required — Current observed state and conditions of the instance
      - `attachedVolumes` Anonymousb84b264f — Contains details about all storage volumes currently attached to this instance
        - `Size` string, string
        - `name` string — Name of the attached volume, corresponding to the PersistentVolume name for persistent volumes or the local disk name for local disks
        - `volumeID` string — Unique identifier of the volume resource, used for mapping volumes to block devices
        - `volumeType` string, required — Type of the attached volume - either 'persistentvolume' or 'localdisk'
      - `conditions` Anonymous119c7e70 — List of conditions representing the current state of various instance subsystems
        - `lastProbeTime` string, date-time
        - `lastTransitionTime` string, date-time
        - `message` string
        - `reason` string
        - `status` string, required
        - `type` string, required
      - `ready` boolean, required — Indicates whether the instance is fully configured and operational
      - `resizing` boolean — Indicates whether the instance is currently being resized to a different instance type
      - `restartRequired` boolean — Indicates whether the instance requires a restart to apply pending changes
      - `restarting` boolean — Indicates whether the instance is currently in the process of restarting
      - `running` boolean, required — Indicates whether the instance's operating system is currently running
      - `runtimeConfiguration` Anonymous65ea3717, nullable — Contains the current runtime configuration settings for the instance, including CPU, memory and other resources
        - `cpu` string, string, required
        - `memory` string, string, required
      - `type` string — The current instance type that defines the cpu, memory and storage capacity
  - `kind` 'InstanceList', required — The string value 'InstanceList' that identifies the schema
  - `metadata` Anonymousa84d7754, required — Standard metadata fields for the list
    - `continue` string
    - `remainingItemCount` integer, nullable
    - `resourceVersion` string
    - `selfLink` string

## Other responses

- `400` — Bad request - invalid configuration provided
- `403` — Forbidden - insufficient permissions

---

[API](https://skmtc.dev/sotoon/apis/sotoon-api.md) · [All operations](https://skmtc.dev/sotoon/apis/sotoon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sotoon/sotoon-api/revisions/c937cd9861c5/schema)