API reference · Schema
Cluster
objectstringrequiredAlways `cluster`: the type of this object
One of
clusteridstringrequiredUnique ID (`clu_…`)
ID with prefix clu_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
project_idstringrequiredProject it belongs to
ID with prefix prj_
namestringrequiredIts name
statestringrequiredprovisioning | running | degraded (a member failed or lost its host; the others keep running and billing) | stopped (billing or host maintenance; only deletion remains) | deleting | deleted
One of
provisioningrunningdegradedstoppeddeletingdeletedstate_reasonstring | nullrequiredWhy it is degraded, stopped or deleted: member_failed, host_lost, shared_volume_unavailable (the host holding the shared volume stopped answering: I/O on it fails on the other members after about two minutes), billing, host_maintenance, requested
member_countintegerrequiredNumber of members
hardwareobjectrequiredWhat each member runs on
ShowHide 3 fields of
hardwareskustringrequiredHardware SKU of every member
display_namestring | nullrequiredThe SKU’s display name
gpus_per_memberintegerrequiredGPUs per member
regionstring | nullrequiredRegion code
imagestringrequiredContainer image every member runs
template_idstring | nullrequiredTemplate it was created from
Environment variables of every member (besides the platform’s own)
ShowHide 2 fields of
envnamestringrequiredVariable name (the CLUSTER_RUNTIME_ prefix is reserved)
valuestringrequiredIts value
Variables taken from project secrets
ShowHide 2 fields of
secret_envnamestringrequiredVariable name
secret_idstringrequiredA secret of this project; its value is set when members start
ID with prefix sec_
commandarray of stringrequiredEntrypoint override
argsarray of stringrequiredCommand override
container_disk_gbintegerrequiredWritable container disk per member
one_member_per_hostbooleanrequiredEvery member was placed on a host of its own
private_networkobjectrequiredHow members reach each other
ShowHide 3 fields of
private_networksubnetstringrequiredIts private network, fixed for the cluster’s life
env_prefixstringrequiredPrefix of the variables the platform sets in every member
launcherstringrequiredPath, inside every member, of the launcher that starts processes on other members (ssh-compatible arguments)
shared_volumeobject | nullrequiredThe shared volume, if the cluster has one
ShowHide 4 fields of
shared_volumevolume_idstringrequiredID of the volume
ID with prefix vol_
size_gbintegerrequiredSize in GB
mount_pathstringrequiredWhere every member mounts it
served_by_rankintegerrequiredThe member whose host holds the data (the head); if that host is lost, the volume is unavailable
Every member, by rank
ShowHide 10 fields of
membersobjectstringrequiredAlways `cluster_member`: the type of this object
One of
cluster_memberrankintegerrequiredIts rank: 0 is the head
hostnamestringrequiredIts name, resolvable on every member
addressstringrequiredIts fixed private address on the cluster’s network
statestringrequiredstarting | running | failed (its container exited or could not start; nothing restarts it) | host_lost | stopped | deleted
One of
startingrunningfailedhost_loststoppeddeletedstate_reasonstring | nullrequiredMachine-readable cause the host reported, when there is one
host_idstringrequiredThe host it was placed on (opaque; members with the same value share a host)
simulated_gpusbooleanrequiredIts host advertises simulated GPUs (development only)
started_atstring (date-time) | nullrequiredWhen its current run started (null when not running)
How to open a shell on it through the SSH gateway (present when reading one cluster)
ShowHide 5 fields of
sshuserstringrequiredSSH user name (the member’s own identity)
hoststringrequiredSSH gateway host
portintegerrequiredSSH gateway port
commandstringrequiredReady-to-run ssh command (uses one of the project’s SSH keys)
known_hostsarray of stringrequiredLines for ~/.ssh/known_hosts pinning the host keys
priceobjectrequiredWhat it costs at today’s prices: compute while members run, storage while the cluster exists
ShowHide 3 fields of
priceper_hourstring | nullrequiredCompute of every member per hour at today’s prices, nano-USD (null if the SKU is not priced)
pattern ^-?[0-9]+$
member_per_hourstring | nullrequiredOne member’s compute per hour, nano-USD
pattern ^-?[0-9]+$
shared_volume_per_hourstringrequiredThe shared volume’s storage per hour, nano-USD (rounded down; billed per GB-second while the cluster exists, running or not)
pattern ^-?[0-9]+$
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
stopped_atstring (date-time) | nullrequiredWhen its compute was stopped, if it was
deleted_atstring (date-time) | nullrequiredWhen it was deleted, if it was
{
"object": "cluster",
"id": "clu_01jc5zq4m8k3v6x9t2w7r0b1e4",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"name": "string",
"state": "provisioning",
"state_reason": "string",
"member_count": 1,
"hardware": {
"sku": "string",
"display_name": "string",
"gpus_per_member": 1
},
"region": "string",
"image": "string",
"template_id": "string",
"env": [
{
"name": "string",
"value": "string"
}
],
"secret_env": [
{
"name": "string",
"secret_id": "sec_01jc5zq4m8k3v6x9t2w7r0b1e4"
}
],
"command": [
"string"
],
"args": [
"string"
],
"container_disk_gb": 1,
"one_member_per_host": true,
"private_network": {
"subnet": "10.224.5.0/24",
"env_prefix": "string",
"launcher": "string"
},
"shared_volume": {
"volume_id": "vol_01jc5zq4m8k3v6x9t2w7r0b1e4",
"size_gb": 1,
"mount_path": "string",
"served_by_rank": 1
},
"members": [
{
"object": "cluster_member",
"rank": 1,
"hostname": "member-0",
"address": "string",
"state": "starting",
"state_reason": "string",
"host_id": "string",
"simulated_gpus": true,
"started_at": "2026-01-01T00:00:00.000Z",
"ssh": {
"user": "string",
"host": "string",
"port": 1,
"command": "string",
"known_hosts": [
"string"
]
}
}
],
"price": {
"per_hour": "1500000000",
"member_per_hour": "1500000000",
"shared_volume_per_hour": "1500000000"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stopped_at": "2026-01-01T00:00:00.000Z",
"deleted_at": "2026-01-01T00:00:00.000Z"
}Used by
- List clusters in the project, newest first (deleted ones only when asked for)
GET /v1/clusters - Create a cluster: every member is placed on a host at once, or nothing is created
POST /v1/clusters - Get a cluster: its state, its members (rank, host, address, state) and how to connect
GET /v1/clusters/{cluster_id} - Rename a cluster (nothing else about a cluster changes after creation)
PATCH /v1/clusters/{cluster_id} - Delete a cluster: every member, its network and its shared volume are destroyed
DELETE /v1/clusters/{cluster_id}