Sign in

v44

latestOpenAPI 3.1.0raw.githubusercontent.com2026-05-20129390589.6 KB
Instances

Get instance

⚠️ This endpoint is in public preview.

Retrieve an instance by ID or name.

get/preview/v2/instances/{id}

Path parameters

idstring required

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

Example:inst_k3R-nX9vLm7Qp2Yw5Jd8F

Response

Instance details.

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
}