Skip to main content
GET
List instances

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

Scope the returned list to a single workspace (ID, resource path, or name). Without it, the returned list spans every workspace where the caller has Instance:List and Instance:Read (granted at either the workspace or organization level). 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"

pool
string[]

Filter by pool (repeatable). Instances on any of the given pools match.

A resource path like 'sfc:pool:acme:prod:my-pool' 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: (pool_[0-9a-zA-Z_-]{1,21})|(sfc:pool:[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.

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

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"