/instances/{id}/info

GET

instances

{id}

info

curl --request GET \
  --url https://api.shadeform.ai/v1/instances/{id}/info \
  --header 'X-API-KEY: <api-key>'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "cloud": "hyperstack",
  "region": "canada-1",
  "shade_instance_type": "A6000",
  "cloud_instance_type": "gpu_1x_a6000",
  "cloud_assigned_id": "13b057d7-e266-4869-985f-760fe75a78b3",
  "shade_cloud": true,
  "name": "cool-gpu-server",
  "configuration": {
    "memory_in_gb": 12,
    "storage_in_gb": 256,
    "vcpus": 6,
    "num_gpus": 1,
    "gpu_type": "A100",
    "interconnect": "pcie",
    "vram_per_gpu_in_gb": 48,
    "os": "ubuntu_22_shade_os"
  },
  "ip": "1.0.0.1",
  "ssh_user": "shadeform",
  "ssh_port": 22,
  "status": "active",
  "cost_estimate": "103.4",
  "hourly_price": 210,
  "volume_ids": [
    "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
  ],
  "ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "vllm/vllm-openai:latest",
      "args": "--model mistralai/Mistral-7B-v0.1",
      "shared_memory_in_gb": 8,
      "envs": [
        {
          "name": "HUGGING_FACE_HUB_TOKEN",
          "value": "hugging_face_api_token"
        }
      ],
      "port_mappings": [
        {
          "host_port": 80,
          "container_port": 8000
        }
      ],
      "volume_mounts": [
        {
          "host_path": "~/.cache/huggingface",
          "container_path": "/root/.cache/huggingface"
        }
      ]
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "auto_delete": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "alert": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "volume_mount": {
    "auto": true
  },
  "tags": [
    "tag1"
  ],
  "envs": [
    {
      "name": "HUGGING_FACE_HUB_TOKEN",
      "value": "hugging_face_api_token"
    }
  ],
  "port_mappings": [
    {
      "internal_port": 8000,
      "external_port": 80
    }
  ],
  "created_at": "2016-08-29T09:12:33.001Z",
  "deleted_at": "2016-08-29T09:12:33.001Z"
}

Authorizations

X-API-KEY

string

header

required

Path Parameters

string

required

The instance id

Response

200 - application/json

Return an instance object.

string

required

The unique identifier for the instance. Used in the instances for the /instances/{id}/info and /instances/{id}/delete APIs.

Example:

"d290f1ee-6c54-4b01-90e6-d701748f0851"

cloud

enum<string>

required

Specifies the underlying cloud provider. See this explanation for more details.

Available options:

aws,

azure,

lambdalabs,

tensordock,

runpod,

latitude,

jarvislabs,

oblivus,

paperspace,

datacrunch,

massedcompute,

vultr

Example:

"hyperstack"

region

string

required

Specifies the region.

Example:

"canada-1"

shade_instance_type

string

required

The Shadeform standardized instance type. See this explanation for more details.

Example:

"A6000"

cloud_instance_type

string

required

The instance type for the underlying cloud provider. See this explanation for more details.

Example:

"gpu_1x_a6000"

cloud_assigned_id

string

required

The unique identifier of the instance issued by the underlying cloud provider.

Example:

"13b057d7-e266-4869-985f-760fe75a78b3"

shade_cloud

boolean

required

Specifies if the instance is launched in Shade Cloud or in a linked cloud account.

Example:

true

name

string

required

The name of the instance

Example:

"cool-gpu-server"

configuration

object

required

string

required

The public IP address of the instance. In select cases, it may also be the DNS.

Example:

"1.0.0.1"

ssh_user

string

required

The SSH user used to SSH into the instance.

Example:

"shadeform"

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.

Example:

22

status

enum<string>

required

The status of the instance.

Available options:

pending,

active,

deleted

Example:

"active"

cost_estimate

string

required

The cost incurred by the instance. This only the cost via Shadeform. If the instance is deployed in your own cloud account, then all billing is through your cloud provider.

Example:

"103.4"

created_at

string

required

The timestamp of when the instance was created in UTC.

Example:

"2016-08-29T09:12:33.001Z"

deleted_at

string

required

The timestamp of when the instance was deleted in UTC.

Example:

"2016-08-29T09:12:33.001Z"

hourly_price

integer

The hourly price of the instance in cents.

Example:

210

volume_ids

string[]

List of volume IDs to be mounted. Currently only supports 1 volume at a time.

The ID of the storage volume.

ssh_key_id

string

The ID of the SSH Key.

Example:

"78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"

launch_configuration

object

Defines automatic actions after the instance becomes active.

launch_configuration.type

enum<string>

required

Specifies the type of launch configuration. See Launch Configuration for more details.

Available options:

docker,

script

Example:

"docker"

launch_configuration.docker_configuration

object

May only be used if launch_configuration.type is 'docker'. Use docker_configuration to automatically pull and run a docker image. See this tutorial for examples.

launch_configuration.docker_configuration.image

string

required

Specifies the docker image to be pulled and run on the instance at startup.

Example:

"vllm/vllm-openai:latest"

launch_configuration.docker_configuration.args

string

Specifies the container arguments passed into the image at runtime.

Example:

"--model mistralai/Mistral-7B-v0.1"

launch_configuration.docker_configuration.shared_memory_in_gb

integer

Describes the amount of shared memory allocated for the container. Equivalent to using the --shm-size flag in the docker cli. If shared_memory_in_gb is not specified, then the container will use the host namespace which is the equivalent of --ipc=host.

Example:

8

launch_configuration.docker_configuration.envs

object[]

List of environment variable name-value pairs that will be passed to the docker container.

Environment variables for the container image.

launch_configuration.docker_configuration.port_mappings

object[]

List of port mappings between the host instance and the docker container. Equivalent of -p flag for docker run command.

Maps the public instance port to a port on the container.

launch_configuration.docker_configuration.volume_mounts

object[]

List of volume mounts between the host instance and the docker container. Equivalent of -v flag for docker run command.

Mounts the host volume to a container file path.

launch_configuration.script_configuration

object

May only be used if launch_configuration.type is 'script'. Configures a startup script to be run automatically after the instance is active. See this [tutorial]/guides/startupscript) for examples.

auto_delete

object

Set a date or spend threshold to automatically delete the instance

alert

object

Set a date or spend threshold to receive an email alert

volume_mount

object

Settings for mounting volumes onto file systems

tags

string[]

Add custom, searchable tags to instances.

Tag for searching and grouping

envs

object[]

List of environment variable name and values to automatically add to the instance

Environment variables for the container image.

port_mappings

object[]

List of port mappings on an instance that a Cloud Provider might have automatically set up.

/instances/create /instances/{id}/update

curl --request GET \
  --url https://api.shadeform.ai/v1/instances/{id}/info \
  --header 'X-API-KEY: <api-key>'

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "cloud": "hyperstack",
  "region": "canada-1",
  "shade_instance_type": "A6000",
  "cloud_instance_type": "gpu_1x_a6000",
  "cloud_assigned_id": "13b057d7-e266-4869-985f-760fe75a78b3",
  "shade_cloud": true,
  "name": "cool-gpu-server",
  "configuration": {
    "memory_in_gb": 12,
    "storage_in_gb": 256,
    "vcpus": 6,
    "num_gpus": 1,
    "gpu_type": "A100",
    "interconnect": "pcie",
    "vram_per_gpu_in_gb": 48,
    "os": "ubuntu_22_shade_os"
  },
  "ip": "1.0.0.1",
  "ssh_user": "shadeform",
  "ssh_port": 22,
  "status": "active",
  "cost_estimate": "103.4",
  "hourly_price": 210,
  "volume_ids": [
    "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40"
  ],
  "ssh_key_id": "78a0dd5a-dbb1-4568-b55c-5e7e0a8b0c40",
  "launch_configuration": {
    "type": "docker",
    "docker_configuration": {
      "image": "vllm/vllm-openai:latest",
      "args": "--model mistralai/Mistral-7B-v0.1",
      "shared_memory_in_gb": 8,
      "envs": [
        {
          "name": "HUGGING_FACE_HUB_TOKEN",
          "value": "hugging_face_api_token"
        }
      ],
      "port_mappings": [
        {
          "host_port": 80,
          "container_port": 8000
        }
      ],
      "volume_mounts": [
        {
          "host_path": "~/.cache/huggingface",
          "container_path": "/root/.cache/huggingface"
        }
      ]
    },
    "script_configuration": {
      "base64_script": "IyEvYmluL2Jhc2gKCiMgRW5kbGVzcyBsb29wCndoaWxlIHRydWUKZG8KICAgICMgRmV0Y2ggYSBjYXQgZmFjdCB3aXRoIGEgbWF4aW11bSBsZW5ndGggb2YgMTQwIGNoYXJhY3RlcnMKICAgIGN1cmwgLS1uby1wcm9ncmVzcy1tZXRlciBodHRwczovL2NhdGZhY3QubmluamEvZmFjdD9tYXhfbGVuZ3RoPTE0MAoKICAgICMgUHJpbnQgYSBuZXdsaW5lIGZvciByZWFkYWJpbGl0eQogICAgZWNobwoKICAgICMgU2xlZXAgZm9yIDMgc2Vjb25kcyBiZWZvcmUgdGhlIG5leHQgaXRlcmF0aW9uCiAgICBzbGVlcCAzCmRvbmUKCgo="
    }
  },
  "auto_delete": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "alert": {
    "date_threshold": "2006-01-02T15:04:05-07:00",
    "spend_threshold": "3.14"
  },
  "volume_mount": {
    "auto": true
  },
  "tags": [
    "tag1"
  ],
  "envs": [
    {
      "name": "HUGGING_FACE_HUB_TOKEN",
      "value": "hugging_face_api_token"
    }
  ],
  "port_mappings": [
    {
      "internal_port": 8000,
      "external_port": 80
    }
  ],
  "created_at": "2016-08-29T09:12:33.001Z",
  "deleted_at": "2016-08-29T09:12:33.001Z"
}

Instances

SSH Keys

Volumes

Templates

API Documentation

Authorizations

Path Parameters

Response