API reference · Clusters
Delete a cluster: every member, its network and its shared volume are destroyed
/v1/clusters/{cluster_id}- TypeScript
client.clusters.delete()- Python
client.clusters.delete()- CLI
hayonix clusters delete
Irreversible. Billing ends with each member’s container and the shared volume’s data is deleted on its host. Deleting a deleted cluster returns it unchanged.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the cluster:delete permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS -X DELETE "$API_BASE_URL/clusters/clu_01jc5zq4m8k3v6x9t2w7r0b1e4" \
-H "Authorization: Bearer $API_KEY"Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Path parameters
cluster_idstringrequiredID of the cluster
ID with prefix clu_
Response
200 Cluster — The cluster (deleting)
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
Example response
{
"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"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
409 | conflict_error | The resource's current state does not allow this. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |