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": "<string>",
      "resource_path": "<string>",
      "owner": "<string>",
      "workspace": "<string>",
      "name": "<string>",
      "object": "instance",
      "status": "awaiting_allocation",
      "capacity": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
      "created_at": 1738972800,
      "image": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
      "cloud_init_user_data_used": true,
      "instance_sku": {
        "id": "<string>",
        "name": "<string>"
      },
      "deployment": "depl_k3R-nX9vLm7Qp2Yw5Jd8F",
      "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
      "tags": {
        "env": "prod",
        "team": "infra"
      },
      "expected_shutdown_at": 1738972800
    }
  ],
  "cursor": "nodec_gqXR7s0Kj5mHvE2wNpLc4Q"
}

Documentation Index

Fetch the complete documentation index at: https://docs.sfcompute.com/llms.txt

Use this file to discover all available pages before exploring further.

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:prod: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,3})
Example:

"wksp_k3R-nX9vLm7Qp2Yw5Jd8F"

​
id
string[]

Filter by instance ID (repeatable).

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

Filter by capacity. 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._-]+){1,3})
Example:

"cap_k3R-nX9vLm7Qp2Yw5Jd8F"

​
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
​
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"
​
expand
enum<string>[]

Fields to expand with full objects instead of IDs.

Available options:
capacity,
image,
deployment
​
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"