Skip to main content
GET
/
preview
/
v2
/
instances
List instances
curl --request GET \
  --url https://api.sfcompute.com/preview/v2/instances \
  --header 'Authorization: Bearer <token>'
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "inst_k3R-nX9vLm7Qp2Yw5Jd8F",
      "resource_path": "<string>",
      "owner": "<string>",
      "workspace": "<string>",
      "workspace_id": "<string>",
      "name": "<string>",
      "object": "instance",
      "capacity": {
        "id": "<string>",
        "name": "<string>"
      },
      "created_at": 1738972800,
      "image": {
        "id": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
        "name": "<string>"
      },
      "cloud_init_user_data_used": true,
      "instance_sku": {
        "id": "isku_k3R-nX9vLm7Qp2Yw5Jd8F",
        "name": "<string>"
      },
      "deployment": {
        "id": "<string>",
        "name": "<string>"
      },
      "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
      "tags": {
        "env": "prod",
        "team": "infra"
      },
      "expected_shutdown_at": 1738972800
    }
  ],
  "cursor": "nodec_gqXR7s0Kj5mHvE2wNpLc4Q"
}

Authorizations

​
Authorization
string
header
required

Create an API token using sf tokens create or at https://sfcompute.com/account/api-keys.

Query Parameters

​
workspace
string
required

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

Pattern: (wksp_[0-9a-zA-Z_-]{1,21})|(sfc:workspace:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){1,1})
Example:

"wksp_k3R-nX9vLm7Qp2Yw5Jd8F"

​
id
string[]

Filter by instance ID (repeatable).

Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.

Pattern: inst_[0-9a-zA-Z_-]{1,21}
Example:

"inst_k3R-nX9vLm7Qp2Yw5Jd8F"

​
capacity
string[]

Filter by capacity (repeatable). Instances on any of the given capacities match.

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.

Pattern: (cap_[0-9a-zA-Z_-]{1,21})|(sfc:capacity:[a-zA-Z0-9._-]+(:[a-zA-Z0-9._-]+){2,2})
​
status
enum<string>[]

Filter by instance status (repeatable).

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.

Available options:
awaiting_allocation,
running,
terminated,
failed
​
created_after
integer<int64>

Filter to instances created at or after this Unix timestamp (seconds).

​
created_before
integer<int64>

Filter to instances created at or before this Unix timestamp (seconds).

​
instance_sku
string[]

Filter by instance SKU (repeatable). Instances on any of the given SKUs match.

Accepts the canonical prefix below; additional legacy prefixes are aliased for read compatibility. Writes always emit the canonical form.

Pattern: isku_[0-9a-zA-Z_-]{1,21}
Example:

"isku_k3R-nX9vLm7Qp2Yw5Jd8F"

​
limit
integer<u-int32>
default:50
Required range: 1 <= x <= 200
​
starting_after
string

Cursor for forward pagination (from a previous response's cursor field).

Pattern: ^nodec_[A-Za-z0-9_-]+$
Example:

"nodec_gqXR7s0Kj5mHvE2wNpLc4Q"

​
ending_before
string

Cursor for backward pagination.

Pattern: ^nodec_[A-Za-z0-9_-]+$
Example:

"nodec_gqXR7s0Kj5mHvE2wNpLc4Q"

​
include
string[]

Additional fields to include in the response.

Allowed value: "cloud_init_user_data"
​
tag
string[]

Filter by tag key-value pair (repeatable). Format: key=value (the = between key and value must be percent-encoded in the URL).

​
tag_key
string[]

Filter by tag key existence (repeatable). Returns resources that have a tag with this key, regardless of the value.

Response

Paginated list of instances.

​
object
string
default:list
required
read-only
Allowed value: "list"
​
has_more
boolean
required
​
data
object[]
required
​
cursor
null | string

Pass as starting_after or ending_before to paginate.

Pattern: ^nodec_[A-Za-z0-9_-]+$
Example:

"nodec_gqXR7s0Kj5mHvE2wNpLc4Q"