Skip to main content
GET
/
v2
/
nodes
List nodes
curl --request GET \
  --url https://api.sfcompute.com/v2/nodes \
  --header 'Authorization: Bearer <token>'
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "<string>",
      "resource_path": "<string>",
      "owner": "<string>",
      "workspace": "<string>",
      "name": "<string>",
      "object": "node",
      "status": "awaiting_allocation",
      "capacity": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
      "created_at": 1738972800,
      "image": "image_k3R-nX9vLm7Qp2Yw5Jd8F",
      "cloud_init_user_data_used": true,
      "zone": "richmond",
      "deployment": "depl_k3R-nX9vLm7Qp2Yw5Jd8F",
      "cloud_init_user_data": "IyEvYmluL2Jhc2gKZWNobyBoZWxsbyB3b3JsZAo=",
      "tags": {
        "env": "prod",
        "team": "infra"
      }
    }
  ],
  "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: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 node ID (repeatable).

Pattern: node_[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 node status (repeatable).

awaiting_allocation when waiting for compute allocation on its capacity, running once assigned and physical node is running (still takes time for image to be downloaded and booted), terminated when stopped by 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 nodes.

​
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"