v1

latestOpenAPI 3.1.02026-07-2665179189.7 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.

resource_pathstring required

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

ownerstring required

workspacestring required

workspace_idstring 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.

Values are not exhaustive across API versions. Clients should tolerate new statuses.

created_atinteger required

Unix timestamp.

updated_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.

enable_public_ipv4boolean

Whether this instance requires a public IPv4 address. When false, only SSH (TCP port 22) is open on the instance and no other ports accept inbound traffic.

public_ipstring

Public IPv4 address assigned to this instance. Present only when enable_public_ipv4 = true; omitted otherwise.

firewallstring

tagsTags

expected_shutdown_atinteger

Unix timestamp.

priority_level'yield' | 'normal' | 'preferred' | 'critical'

Instance priority — a relative ranking that determines which instances the system prefers to keep running when capacity is constrained. When a capacity's quota drops below its running-instance count, instances are terminated in priority order (lower first).

Ordering: yield < normal < preferred < critical.

Example response

{
  "id": "inst_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:instance:<account_id>:<workspace>:<name>",
  "owner": "my-resource-name",
  "workspace": "my-resource-name",
  "workspace_id": "wksp_k3R-nX9vLm7Qp2Yw5Jd8F",
  "name": "my-resource-name",
  "instance_sku": {
    "id": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
    "alias": "my-resource-name"
  },
  "capacity": {
    "id": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "pool": {
    "id": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "created_at": 1738972800,
  "updated_at": 1738972800,
  "image": {
    "id": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "managed_by": {
    "id": "depl_k3R-nX9vLm7Qp2Yw5Jd8F",
    "name": "my-resource-name"
  },
  "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
  "firewall": "frwl_k3R-nX9vLm7Qp2Yw5Jd8F",
  "tags": {
    "env": "prod",
    "team": "infra"
  },
  "expected_shutdown_at": 1738972800
}