---
title: "/instances"
method: GET
path: "/instances"
---

# /instances

`GET /instances`

Get all active and pending instances for the account associated with the api key passed in through the x-api-key header. When an instance is created, it should immediately be displayed as an item in the response of this API.

## Response `200`

Returns an InstancesResponse object

- InstancesResponse
  - `instances` Instance[], required
    - `id` string, uuid, required — The unique identifier for an instance managed by Shadeform. Used in the endpoint for the /instances/{id}/info and /instances/{id}/delete APIs.
    - `cloud` 'aws' | 'azure' | 'lambdalabs' | 'tensordock' | 'runpod' | 'latitude' | 'jarvislabs' | 'oblivus' | 'paperspace' | 'datacrunch' | 'massedcompute' | 'vultr', required — Specifies the underlying cloud provider that the instance is launched in. For the latest list of supported clouds, call the /instances/types API for all clouds.
    - `region` string, required — Specifies the region in the underlying cloud provider that the instance is launched in. For the latest list of supported regions per cloud, call the instances/types API for all regions.
    - `shade_instance_type` string, required — The Shadeform standardized instance identifier for instances with a specific GPU configuration. We map the standardized Shade Instance Type to each cloud provider's instance type. For example, launching an 'A100' Shade Instance Type in TensorDock and in Paperspace will ensure that both instances will have an A100 GPU.
    - `cloud_instance_type` string, required — The instance type for the underlying cloud provider. The CloudInstanceType is determined by the combination of the shade_instance_type, cloud, and num_gpus fields
    - `cloud_assigned_id` string, required — The unique identifier of the instance issued by the underlying cloud provider. This value is not useful at this time.
    - `shade_cloud` boolean, required — If Shade Cloud is true, the instance will be launched in Shadeform's managed account. If Shade Cloud is false, Shadeform will check if you have provided an API Access Key for the specified cloud and launch the instance into your own cloud provider account. To launch in your own cloud provider account, you need to add your API Access Key for the cloud via the Shadeform Cloud Access Settings page at https://platform.shadeform.ai/settings/cloudaccess.
    - `name` string, required — The name of the instance
    - `configuration` object, required
      - `memory_in_gb` integer, required — The amount of memory for the instance in gigabytes. Note that this is not VRAM. VRAM is determined by the GPU type and the number of GPUs.
      - `storage_in_gb` integer, required — The amount of storage for the instance. If this storage is too low for the instance type, please email founders@shadeform.ai as the storage may be adjustable.
      - `vcpus` integer, required — The number of vCPUs for the instance.
      - `num_gpus` integer, required — The number of GPUs for the instance.
      - `gpu_type` string, required — The type of GPU for the instance.
      - `interconnect` string, required — The type of interconnect for the GPU.
      - `os` string, required — The operating system of the instance.
    - `ip` string, required — The public IP address of the instance. In select cases, it may also be the DNS.
    - `ssh_user` string, required — The SSH user used to SSH into the instance.
    - `ssh_port` integer, required — The SSH port of the instance. In most cases, this will be port 22 but for some clouds, this may be a different port.
    - `status` 'pending' | 'active' | 'deleted', required — The status of the instance.
    - `cost_estimate` string, required — The cost incurred by the instance. This cost is only the cost billed by Shadeform. This does not include the underlying cloud provider cost if you are managing instances in your own cloud provider account.
    - `hourly_price` integer, required — The base hourly price of the instance in cents. This cost does not include the Shadeform platform fee.
    - `launch_configuration` LaunchConfiguration — Defines steps that can be automatically run on the instance after launching
      - `type` 'docker', required — Specifies the type of launch configuration. Currently only 'docker' is supported.
      - `args` string — When the docker launch configuration type is specified, this field describes the docker args to be attached to the docker run command.
      - `image` string, required — When the docker launch configuration type is specified, this field describes the docker image to be pulled and run on the instance at startup.
    - `created_at` string, date-time, required — The timestamp of when the instance was created in UTC.
    - `deleted_at` string, date-time, required — The timestamp of when the instance was deleted in UTC

## Changes

- **2024-01-11** `7d5677457388` — 19 warning, 11 info
  - removed the optional property `instances/items/active_at` from the response with the `200` status
  - removed the optional property `instances/items/boot_time` from the response with the `200` status
  - removed the optional property `instances/items/launch_configuration/docker_configuration` from the response with the `200` status
  - removed the optional property `instances/items/launch_configuration/script_configuration` from the response with the `200` status
  - …26 more

[Change history](https://skmtc.dev/shadeform/apis/shadeform-api/changes/instances/get.md)

---

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