Sign in
Instances

Create instance

⚠️ This endpoint is in public preview.

Create an instance.

post/preview/v2/instances

Request body

namestring
capacitystring required

A resource path like 'sfc:capacity:acme:prod:my-capacity' or an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.

imagestring required

A resource path like 'sfc:image:acme:prod:my-image' or an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.

cloud_init_user_datastring byte

Base64-encoded cloud-init user data. Maximum 64KB.

tagsSfcApiTags
priorityinteger nullable

Shutdown priority. Higher numbers are kept longer. Defaults to 0.

_preview_enable_infinibandboolean

Experimental — subject to change or removal without notice. Enables InfiniBand. The chosen instance_sku must support InfiniBand.

Example request

{
  "name": "my-resource-name",
  "capacity": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
  "image": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "tags": {
    "env": "prod",
    "team": "infra"
  }
}

Response

Instance created.

idstring required
resource_pathstring required

A resource path for a instance resource. Format: sfc:instance:<account>:<workspace>:<name>.

ownerstring required
workspacestring required
namestring required
object'instance' required
status'awaiting_allocation' | 'running' | 'terminated' | 'failed' required

awaiting_allocation when waiting for compute allocation on its capacity, running once assigned and the physical machine is running (still takes time for the image to be downloaded and booted), terminated when stopped by the user or after running out of allocation, failed on hardware fault.

created_atinteger required

Unix timestamp.

cloud_init_user_data_usedboolean required

Whether cloud-init user data is configured for this instance.

cloud_init_user_datastring byte

Base64-encoded cloud-init user data.

tagsSfcApiTags
expected_shutdown_atinteger

Unix timestamp.

priorityinteger required

Shutdown priority. Higher numbers are kept longer when the capacity's quota drops below the running-instance count. Default 0; any signed 64-bit integer is accepted.

Example response

{
  "id": "inst_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:instance:<account_id>:<workspace>:<name>",
  "owner": "my-resource-name",
  "workspace": "my-resource-name",
  "name": "my-resource-name",
  "object": "instance",
  "instance_sku": {
    "id": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "capacity": {
    "id": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "created_at": 1738972800,
  "image": {
    "id": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "deployment": {
    "id": "depl_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "tags": {
    "env": "prod",
    "team": "infra"
  },
  "expected_shutdown_at": 1738972800
}

Changes

Changed in 2 of the 44 revisions of this API.12