Order a cluster | EmpirioLabs AI Docs

Reserve a cluster. Every node is allocated together or none is, and the nodes are billed as one unit from the moment the group is created.

Send the id of a cluster from GET /v1/gpu/clusters. Use nodes to take part of it, from 2 up to the nodes in the offer; omit it to take all of them. Set max_price_hourly to the price of the size you are ordering: price_hourly / nodes in the offer, times the count you send. The order is refused above that figure, so you are never charged more than you saw.

Cluster storage is one shared object bucket or network volume across all nodes. volume_id is optional, and must be an object bucket or network volume when supplied. Workspace volumes cannot be attached to a cluster.

Authentication

AuthorizationBearer

Pass your EmpirioLabs API key as a bearer token. The Anthropic-style x-api-key header is also accepted on every endpoint.

Request

This endpoint expects an object.

cluster_idstringRequired

The id from GET /v1/gpu/clusters.

templatestringRequired

Multi-node workload to run on every node.

nodesintegerOptional>=2

How many of the offered nodes to reserve. Defaults to all of them.

volume_idstringOptional

Optional object bucket mounted at /mnt/<name>, or network volume mounted at /workspace, shared by every node.

max_price_hourlydoubleOptional

Total $/hr you accepted for the size you are ordering. The order is refused above it.

Response

The cluster was ordered.

cluster_idstringOptional

nodesintegerOptional

price_hourlydoubleOptional

storagestring or nullOptional

instanceslist of stringsOptional

One instance id per node. Each behaves like an ordinary GPU instance.

Errors

402

Payment Required Error

409

Conflict Error