# 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](/api-reference/volumes.md#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"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sesterce.com/api-reference/gpu-cloud-instances.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.