---
title: "Create spot instance"
method: POST
path: "/v1/spot-instances"
tags: ["Spot instances"]
---

# Create spot instance

`POST /v1/spot-instances`

## Request

- Base URL: `https://api.emma.ms/external`
- URL: `https://api.emma.ms/external/v1/spot-instances`
- Auth: HTTP bearer

This method creates a spot instance according to the specified parameters.

A Spot Instance is a specialized compute instance that allows you to access and utilize unused instance capacity at a steeply discounted rate. Spot price is charged on an hourly basis.

To create a spot instance, follow these steps:

1. Select a data center using the `/v1/data-centers` endpoint. The data center determines the provider and location of the spot instance.

2. Select an available hardware configuration for the spot instance using the `/v1/spots-configs` endpoint.

To create a GPU spot instance, include `acceleratorTypeId` and `accelerators` fields in the request body. Obtain these values from the selected configuration in the GET /v1/spots-configs response.

3. Select an SSH key for the Linux spot instance using the `/v1/ssh-keys` endpoint.

4. Select an operating system using the `/v1/operating-systems` endpoint.

5. Choose one of the cloud network types: _multi-cloud_, _isolated,_ or _default_. Choose the _multi-cloud_ network type if you need to connect compute instances from different providers.
       
You may choose not to specify a security group. In this case, the spot instance will be added to the default security group.
        
A `price` field of a spot instance is required. 

The spot instance market operates on a bidding system. Your specified price acts as your bid in this market. If your bid is higher than the current spot price, your instance request will likely be fulfilled. However, if the market price exceeds your bid, your instance may not be launched or could be terminated if already running.

## Request body

- SpotCreate
  - `name` string, required: Name of the spot instance
  - `dataCenterId` string, required: ID of the provider's data center
  - `osId` integer, required: ID of the operating system
  - `cloudNetworkType` 'isolated' | 'multi-cloud' | 'default', required: Type of the cloud network
  - `vCpuType` 'shared' | 'standard' | 'hpc', required: Type of the Central Processing Units (vCPUs)
  - `vCpu` integer, required: Number of virtual Central Processing Units (vCPUs)
  - `ramGb` integer, required: Capacity of the RAM in gigabytes
  - `volumeType` 'ssd' | 'ssd-plus', required: Volume type
  - `volumeGb` integer, required: Capacity of the volume in gigabytes
  - `sshKeyId` integer, nullable: SSH-key ID
  - `userPassword` string, nullable: User password
  - `securityGroupId` integer: ID of the security group
  - `acceleratorTypeId` string, nullable: GPU accelerator type identifier. Obtain from the acceleratorTypeId field in the GET /v1/spots-configs response. Required when creating a GPU spot instance.
  - `accelerators` number, nullable: Number of GPU accelerators. Must match the value from the selected configuration in GET /v1/spots-configs. Required when acceleratorTypeId is specified.
  - `price` number, required: Offer price of the spot instance
  - `initScript` string, nullable: Optional bash script to execute after the spot instance is created. Supported for Linux operating systems only — providing initScript for a Windows osId returns 422.
  - `installSystemKey` boolean, nullable: Install the emma system SSH key on the spot instance. Not supported for Windows operating system or VMware provider.

## Response `200`

Spot instance created

- SpotVm
  - `id` integer: ID of the virtual machine
  - `createdAt` string: Date and time when the virtual machine was created
  - `createdByName` string: Name of the user who created the virtual machine
  - `createdById` integer: ID of the user who created the virtual machine
  - `modifiedAt` string: Date and time when the virtual machine was last edited
  - `modifiedByName` string: Name of the user who last edited the virtual machine
  - `modifiedById` integer: ID of the user who last edited the virtual machine
  - `name` string: Name of the virtual machine
  - `projectId` integer: Project ID
  - `status` 'POWERED_ON' | 'POWERED_OFF' | 'BUSY' | 'DRAFT': Status of the virtual machine
  - `provider` object
    - `id` integer: ID of the cloud provider
    - `name` string: Name of the cloud provider
  - `location` object
    - `id` integer: ID of the data center location
    - `name` string: Name of the data center location (city or state)
    - `country` string: Country of the data center location
    - `continent` string: Name of the geographical continent
    - `region` string: Name of the geographical region
    - `latitude` number, double: Approximate latitude of the geographical location
    - `longitude` number, double: Approximate longitude of the geographical location
  - `dataCenter` object
    - `id` string: Data center ID
    - `name` string: Data center name
    - `providerId` integer: ID of the cloud provider
    - `providerName` string: Name of the cloud provider
    - `locationId` integer: ID of the data center location
    - `locationName` string: Name of the data center location
  - `os` object
    - `id` integer: ID of the operating system
    - `family` string: Family of the operating system
    - `architecture` string: Architecture of the operating system
    - `type` string: Type of the operating system
    - `version` string: Version of the operating system
  - `vCpu` integer: Number of virtual Central Processing Units (vCPUs)
  - `vCpuType` 'shared' | 'standard' | 'hpc': Type of virtual Central Processing Units (vCPUs)
  - `cloudNetworkType` 'isolated' | 'multi-cloud' | 'default': Cloud network type
  - `ramGb` integer: Capacity of the RAM in gigabytes
  - `disks` object[]: List of volumes
    - `id` integer: Volume ID
    - `name` string: Volume name
    - `sizeGb` integer: Volume size in gigabytes
    - `typeId` integer: ID of the volume type
    - `type` string: Volume type
    - `isBootable` boolean: Indicates whether the volume is bootable or not
    - `deviceIdentifier` string, nullable: Device identifier of the volume as seen by the operating system
  - `networks` object[]
    - `id` integer: Network ID
    - `ip` string: Network IP
    - `networkTypeId` integer: ID of the network type
    - `networkType` string: Network type
  - `securityGroup` object
    - `id` integer: ID of the security group
    - `name` string: Name of the security group
  - `sshKeyId` integer: SSH key ID
  - `userName` string: User name
  - `userPassword` string: Administrator password in the Windows operating system
  - `cost` object
    - `unit` string: Cost period
    - `currency` string: Currency of cost
    - `price` number: Cost of the spot instance for the period
    - `minPrice` number: Minimal cost of the spot instance for the period
    - `maxPrice` number: Maximal cost of the spot instance for the period
  - `localDisks` object[], nullable: Local SSD storage directly attached to the host machine. Size is reported in terabytes (TB). Data is ephemeral and will be lost when the spot instance is stopped or deleted.
    - `sizeTb` number: Volume size in TB
    - `typeId` integer: ID of the volume type
    - `type` string: Volume type
  - `accelerator` object, nullable: GPU accelerator attached to the spot instance. Present only for GPU-enabled spot instances. null for standard (non-GPU) instances.
    - `acceleratorTypeId` string: GPU accelerator type ID
    - `acceleratorType` string: GPU accelerator type
    - `accelerators` number: Quantity of GPU accelerators
    - `totalGpuMemoryGb` integer: Total GPU memory
  - `tags` Tag[], nullable
    - `tagId` string, uuid, required: tag id
    - `key` string, required: tag key
    - `value` string, nullable: tag key value
  - `systemKeyInstalled` boolean: Indicates whether the emma system SSH key is installed on the spot instance
  - `workflowExecutionInfo` VmWorkflowExecution, nullable: Workflow execution that provisioned the virtual machine
    - `executionId` string, uuid: Id of the workflow execution
    - `workflowTemplateId` integer, nullable: Id of the workflow template that was executed; returned even after the template has been deleted
    - `workflowTemplateName` string: Name of the workflow template
    - `workflowExists` boolean: Whether the workflow template still exists; false when it was deleted, in which case clients must not render a link to the template
    - `status` 'PENDING' | 'RUNNING' | 'SUCCESS' | 'FAILED': Status of the workflow execution
    - `versionId` integer: ID of the workflow version used to create the instance
    - `versionName` string: Name of the workflow version used to create the instance
    - `versionExists` boolean: Whether the workflow version still exists; false when it was deleted, in which case clients must not render a link to the template

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - Access is denied
- `422`: Unprocessable entity
- `500`: Internal server error

---

[API](https://skmtc.dev/emma/apis/public-emma-api.md) - [All operations](https://skmtc.dev/emma/apis/public-emma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/emma/apis/public-emma-api/revisions/9e55f0920078?raw)