GPU clusters (Compute API)

A cluster is 2–8 identical replicas of one configuration in one region, sharing a network filesystem — for multi-node training or a fleet of workers. What a cluster is and how it behaves is described in GPU clusters; this page is the API.

Prerequisites (Compute access, a key with the compute scope, credit) and the shared rules (auth, rate limits, errors) are on the overview.

Endpoints

Method	Path	What it does
GET	/gpu-clusters	Your clusters
POST	/gpu-clusters	Launch
GET	/gpu-clusters/{id}	One cluster
POST	/gpu-clusters/{id}/scale	Change the replica count
POST	/gpu-clusters/{id}/extend	Add hours
GET	/gpu-clusters/{id}/replicas	The running replicas (pod name, status, node)
GET	/gpu-clusters/{id}/shared-filesystems	Filesystems attached to it
DELETE	/gpu-clusters/{id}	Terminate

The per-replica web terminal, upload and browse are console-only.

Quick run

KEY="eco_YOUR_KEY"; API="https://api.ecohash.com"

# Launch: 2 replicas × 1 GPU in atl, 4 hours, with a new shared filesystem
curl -s -X POST $API/gpu-clusters \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "train-2x1",
    "region_id": "atl",
    "gpu_count": 1,
    "replicas": 2,
    "container_image": "public.ecr.aws/a2b7e2y7/ecolink/gpu-base:v0.1.0",
    "estimated_duration_hours": 4,
    "new_shared_filesystems": [{ "name": "train-data", "size_gb": 200, "mount_path": "/data" }]
  }'
# → 202 with the cluster; note "id"

curl -s $API/gpu-clusters/<id> -H "Authorization: Bearer $KEY"             # status
curl -s $API/gpu-clusters/<id>/replicas -H "Authorization: Bearer $KEY"    # the pods

curl -s -X POST $API/gpu-clusters/<id>/scale -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{ "replicas": 4 }'

curl -s -X DELETE $API/gpu-clusters/<id> -H "Authorization: Bearer $KEY"   # terminate

POST /gpu-clusters

Field	Type	Required	Notes
region_id	string	yes	From GET /gpu-instances/availability. The region's GPU type is used — there is no gpu_type field
gpu_count	int	yes	GPUs per replica: 1, 2, 4 or 8
replicas	int	yes	2–8
container_image	string	yes	Platform image or any public image
estimated_duration_hours	int	yes	1–72. Clusters always have a fixed duration; the whole run is held at launch (hourly_rate × gpu_count × replicas × hours)
name	string	no
startup_command	string	no	Runs on every replica
service_port	int	no	Expose this port at https://api.ecohash.com/gpu-clusters/{id}/service/, load-balanced across replicas
interruptible	bool	no	Only where the region's GPU type lists an interruptible rate
template_id	int	no	Launch from a template
shared_filesystems	array	no	Attach existing: [{ "id": 38, "mount_path": "/data" }]
new_shared_filesystems	array	no	Create and attach: [{ "name", "size_gb", "mount_path" }]

Cloud drives cannot be attached to a cluster (one drive mounts to one pod); use a shared filesystem.

Returns 202 Accepted with the cluster (status pending). 402 if the hold cannot be taken; 409 if the region has too few free GPUs for gpu_count × replicas.

The cluster object

Field	Meaning
id, name, region_id, gpu_type, gpu_count, replicas, container_image, startup_command, service_port	What you launched; replicas is the current count after any scale
status	pending → running → stopped; degraded while some replicas are down; failed
hourly_rate_usd	Rate for the whole cluster as launched (per-GPU rate × gpu_count × replicas)
estimated_duration_hours	The fixed duration
endpoint_url	Public URL when service_port is set
created_at, started_at, terminated_at	Billing runs from started_at

GET /gpu-clusters/{id}/replicas

[
  { "name": "cluster-40-0", "status": "Running", "node": "atl-gpu-3" },
  { "name": "cluster-40-1", "status": "Running", "node": "atl-gpu-5" }
]

POST /gpu-clusters/{id}/scale

{ "replicas": 4 }

1–8. Changes the number of running replicas (scaling up needs the GPUs to be free). Billing stays at the rate and hold fixed at launch — scaling does not re-price the cluster. Returns { "id": 40, "replicas": 4 }.

POST /gpu-clusters/{id}/extend

{ "hours": 2 }

Holds hours × hourly_rate_usd now (the rate is already for the whole cluster) and moves the auto-stop time.

DELETE /gpu-clusters/{id}

Terminates all replicas; the cluster's status becomes stopped and unused held credit is refunded once they have stopped. Attached shared filesystems are kept.