# GPU Cloud instances

### Get the list of available offers

Use this endpoint when you want to explore the different GPU instance options available for your project. This is particularly useful when planning new deployments and needing to compare offers to find the best fit in terms of cost and performance.

{% hint style="info" %}
Double-check all inputs in the request body to ensure successful creation.
{% endhint %}

## GET /gpu-cloud/instances/offers

>

```json
{"openapi":"3.0.0","info":{"title":"Cloud Sesterce API","version":"1.0"},"paths":{"/gpu-cloud/instances/offers":{"get":{"operationId":"GPUCloudInstancesController_getInstancesOffers","parameters":[{"name":"x-api-key","in":"header","description":"The API Key secret should be sent through this header to authenticate the request.","required":true,"schema":{"type":"string"}},{"name":"region","required":false,"in":"query","schema":{"type":"string"}},{"name":"numGpus","required":false,"in":"query","schema":{"type":"string"}},{"name":"gpuType","required":false,"in":"query","schema":{"type":"string"}},{"name":"available","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"sort","required":false,"in":"query","schema":{"enum":["price"],"type":"string"}},{"name":"deploymentType","required":false,"in":"query","schema":{"enum":["vm","container","baremetal"],"type":"string"}}],"responses":{"200":{"description":"Returns the list of available offers for instances","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InstanceOfferDto"}}}}},"403":{"description":"API key invalid","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["GPUCloudInstances"]}}},"components":{"schemas":{"InstanceOfferDto":{"type":"object","properties":{"gpuName":{"type":"string"},"gpuCount":{"type":"number"},"nvlink":{"type":"boolean"},"deploymentType":{"type":"string"},"instanceId":{"type":"string"},"cloudInitAvailable":{"type":"boolean"},"cloud":{"$ref":"#/components/schemas/CloudProviderDto"},"configuration":{"$ref":"#/components/schemas/ConfigurationInstanceDto"},"hourlyPrice":{"type":"number"},"availability":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilityDto"}}},"required":["gpuName","gpuCount","nvlink","deploymentType","instanceId","cloudInitAvailable","cloud","configuration","hourlyPrice","availability"]},"CloudProviderDto":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"]},"ConfigurationInstanceDto":{"type":"object","properties":{"ramGB":{"type":"number"},"storageGB":{"type":"number"},"vCpu":{"type":"number"},"vRamGB":{"type":"number"},"os":{"type":"array","items":{"type":"string"}},"interconnect":{"type":"string"}},"required":["ramGB","storageGB","vCpu","vRamGB","os","interconnect"]},"AvailabilityDto":{"type":"object","properties":{"region":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string"},"available":{"type":"boolean"}},"required":["region","name","countryCode","available"]}}}}
```

### Create a GPU Cloud instance

Use this endpoint when you're ready to launch a new GPU instance for a specific project or task. This is the crucial step to deploy new computing resources.

{% hint style="info" %}
You can use query parameters to fine-tune search results and find the best offer for your specific needs
{% endhint %}

## POST /gpu-cloud/instances

>

```json
{"openapi":"3.0.0","info":{"title":"Cloud Sesterce API","version":"1.0"},"paths":{"/gpu-cloud/instances":{"post":{"operationId":"GPUCloudInstancesController_create","parameters":[{"name":"x-api-key","in":"header","description":"The API Key secret should be sent through this header to authenticate the request.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstanceDto"}}}},"responses":{"201":{"description":"Return the created instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceDto"}}}},"403":{"description":"API key invalid","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["GPUCloudInstances"]}}},"components":{"schemas":{"CreateInstanceDto":{"type":"object","properties":{"name":{"type":"string"},"cloudProvider":{"type":"string"},"instanceId":{"type":"string"},"volumeId":{"type":"string"},"region":{"type":"string"},"vm":{"$ref":"#/components/schemas/VirtualMachineDto"},"dockerContainer":{"$ref":"#/components/schemas/DockerContainerDto"},"sshKeyId":{"type":"string"},"sshKey":{"type":"string"}},"required":["name","cloudProvider","instanceId","region"]},"VirtualMachineDto":{"type":"object","properties":{"os":{"type":"string"},"base64CloudInitScript":{"type":"string","description":"Base64 encoded cloud-init script that will be executed during instance initialization"}},"required":["os"]},"DockerContainerDto":{"type":"object","properties":{"image":{"type":"string"}},"required":["image"]},"InstanceDto":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"region":{"type":"object"},"volumes":{"type":"array","items":{"type":"array"}},"status":{"type":"string","enum":["pending","active","error","deleted","deleting"]},"gpuCount":{"type":"number"},"gpuModel":{"type":"string"},"ram":{"type":"number"},"storage":{"type":"number"},"vramPerGpu":{"type":"number"},"vcpus":{"type":"number"},"interconnect":{"type":"string"},"nvlink":{"type":"boolean"},"os":{"type":"string"},"ip":{"type":"string"},"sshUser":{"type":"string"},"sshPort":{"type":"number"},"dockerImage":{"type":"string"},"dockerCommand":{"type":"string"},"hourlyPrice":{"type":"number"},"deletedAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["_id","name","provider","region","volumes","status","gpuCount","gpuModel","ram","storage","vramPerGpu","vcpus","interconnect","nvlink","os","ip","sshUser","sshPort","dockerImage","dockerCommand","hourlyPrice","deletedAt","createdAt","updatedAt"]}}}}
```

{% hint style="warning" %}
Make sure you filled the right OS name, such as `ubuntu24.04_cuda12.4_shade_os`. You can retrieve the os available with the `/gpu-cloud/instances/offers` endpoint.
{% endhint %}

### Get the list of instances created

This endpoint is essential for users who want an overview of all the instances they have created. It is ideal for managing and monitoring current resources.

{% hint style="info" %}
Ensure your API key is active and correctly entered to view your instances.
{% endhint %}

## GET /gpu-cloud/instances

>

```json
{"openapi":"3.0.0","info":{"title":"Cloud Sesterce API","version":"1.0"},"paths":{"/gpu-cloud/instances":{"get":{"operationId":"GPUCloudInstancesController_getUserInstances","parameters":[{"name":"x-api-key","in":"header","description":"The API Key secret should be sent through this header to authenticate the request.","required":true,"schema":{"type":"string"}},{"name":"deploymentType","required":false,"in":"query","schema":{"enum":["vm","container","baremetal"],"type":"string"}}],"responses":{"200":{"description":"Returns the list of user instances","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InstanceDto"}}}}},"403":{"description":"API key invalid","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["GPUCloudInstances"]}}},"components":{"schemas":{"InstanceDto":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"region":{"type":"object"},"volumes":{"type":"array","items":{"type":"array"}},"status":{"type":"string","enum":["pending","active","error","deleted","deleting"]},"gpuCount":{"type":"number"},"gpuModel":{"type":"string"},"ram":{"type":"number"},"storage":{"type":"number"},"vramPerGpu":{"type":"number"},"vcpus":{"type":"number"},"interconnect":{"type":"string"},"nvlink":{"type":"boolean"},"os":{"type":"string"},"ip":{"type":"string"},"sshUser":{"type":"string"},"sshPort":{"type":"number"},"dockerImage":{"type":"string"},"dockerCommand":{"type":"string"},"hourlyPrice":{"type":"number"},"deletedAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["_id","name","provider","region","volumes","status","gpuCount","gpuModel","ram","storage","vramPerGpu","vcpus","interconnect","nvlink","os","ip","sshUser","sshPort","dockerImage","dockerCommand","hourlyPrice","deletedAt","createdAt","updatedAt"]}}}}
```

### Get details about a GPU Cloud instance created

This endpoint is useful when you need to check the details and status of a specific instance, for example, for troubleshooting or configuration verification.

{% hint style="info" %}
Use the instance ID from your list to quickly retrieve detailed information.
{% endhint %}

## GET /gpu-cloud/instances/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"Cloud Sesterce API","version":"1.0"},"paths":{"/gpu-cloud/instances/{id}":{"get":{"operationId":"GPUCloudInstancesController_getInstanceById","parameters":[{"name":"x-api-key","in":"header","description":"The API Key secret should be sent through this header to authenticate the request.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Return the instance's details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceDetailsDto"}}}},"403":{"description":"API key invalid","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["GPUCloudInstances"]}}},"components":{"schemas":{"InstanceDetailsDto":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string","enum":["pending","active","error","deleted","deleting"]},"region":{"type":"object"},"volumes":{"type":"array","items":{"type":"array"}},"sshKey":{"type":"object"},"createdAt":{"format":"date-time","type":"string"},"deletedAt":{"format":"date-time","type":"string"},"isPending":{"type":"boolean"},"hourlyPrice":{"type":"number"},"ip":{"type":"string"},"sshUser":{"type":"string"},"sshPort":{"type":"number"},"portForwards":{"type":"array","items":{"type":"string"}},"gpuCount":{"type":"number"},"gpuModel":{"type":"string"},"ram":{"type":"number"},"storage":{"type":"number"},"vramPerGpu":{"type":"number"},"vcpus":{"type":"number"},"interconnect":{"type":"string"},"nvlink":{"type":"boolean"},"os":{"type":"string"},"dockerImage":{"type":"string"},"dockerCommand":{"type":"string"}},"required":["_id","name","provider","status","region","volumes","sshKey","createdAt","deletedAt","isPending","hourlyPrice","ip","sshUser","sshPort","portForwards","gpuCount","gpuModel","ram","storage","vramPerGpu","vcpus","interconnect","nvlink","os","dockerImage","dockerCommand"]}}}}
```

### Delete a GPU Cloud instance

{% hint style="info" %}
If needed, ensure data backup before deleting instances to prevent data loss. Discover how to create persistent storage [through the following endpoint](https://docs.sesterce.com/volumes#create-a-new-volume).
{% endhint %}

Use this endpoint when you want to free up resources by deleting an instance that is no longer needed, optimizing your resource usage and costs.

## DELETE /gpu-cloud/instances/{id}

>

```json
{"openapi":"3.0.0","info":{"title":"Cloud Sesterce API","version":"1.0"},"paths":{"/gpu-cloud/instances/{id}":{"delete":{"operationId":"GPUCloudInstancesController_deleteInstance","parameters":[{"name":"x-api-key","in":"header","description":"The API Key secret should be sent through this header to authenticate the request.","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Instance deleted successfully"},"403":{"description":"API key invalid","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"timestamp":{"type":"string"},"path":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["GPUCloudInstances"]}}}}
```