Create a cluster
Creates a multi-node cluster. compute sets the homogeneous
pod shape; the container configuration applies to every pod and can be spread
from a template response.
Authorizations
Runpod API key authentication. Generate an API key in the Runpod console and send it in the Authorization header as Bearer <api_key>. Keys are scoped to the permissions granted when created; requests may return 403 when a valid key lacks access to the requested resource or action.
Body
Request body for creating a cluster. compute defines the
homogeneous pod shape; the container configuration (image, env, ports,
…) applies to every pod and can be spread from a template response.
Private registries are not yet supported for clusters — there is no
registry field here, unlike the other create requests.
1"my-training-cluster"
Cluster type. TRAINING is the generic distributed-training cluster; SLURM provisions a managed Slurm controller/compute topology; RAY provisions a managed Ray head/worker topology; APPLICATION is a general multi-node application cluster.
APPLICATION, TRAINING, SLURM, RAY "TRAINING"
The homogeneous compute shape of a cluster. Every pod in the cluster is identical: podCount pods, each with gpuCountPerPod GPUs of type gpuTypeId. Total GPUs = podCount * gpuCountPerPod.
Docker image reference
"runpod/pytorch:2.8.0-py3.11-cuda12.8.1"
Arguments passed to the container entrypoint
""
Container disk in GB (ephemeral, wiped on restart)
x >= 150
Exposed ports, formatted as port/protocol
Environment variables as key-value pairs
Provision SSH access on every member pod: injects a PUBLIC_KEY environment variable carrying your account's registered SSH public key. Same semantics as the pod create flag.
Start Jupyter on every member pod, as on pod create.
Storage mounts attached to a pod. At-most-one of persistent or
network may be set today (mutually exclusive, enforced at the
handler with 400 if both are present). The network field is an
array for forward compatibility with eventual multi-network-volume
support, but maxItems is 1 today.
PATCH semantics:
- Omitting
mountsor sending{}leaves the existing mount unchanged. - An explicit
network: []is rejected with 400 (clearing mounts is not supported). - Mount kind is fixed at create — a PATCH that introduces a kind not present at create (persistent on a network pod, network on a persistent pod, or any mount on a previously-mountless pod) is rejected with 400.
- The
volumeIdof a network mount is immutable; a PATCH that names a differentvolumeIdis rejected with 400. - Partial mounts are not supported — every mount entry must
include the full schema (
size+pathfor persistent,volumeId+pathfor network). Missing required fields → 422.
Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose. A cluster is always placed within a single data center.
Response
Created
A cluster. Cluster-level fields describe the identity and homogeneous shape; pods is a lightweight summary of the members. Fetch the full member pods — with their container config, mounts, and runtime state — from GET /v2/clusters/{id}/pods.
"cluster_abc123"
"my-training-cluster"
Cluster type. TRAINING is the generic distributed-training cluster; SLURM provisions a managed Slurm controller/compute topology; RAY provisions a managed Ray head/worker topology; APPLICATION is a general multi-node application cluster.
APPLICATION, TRAINING, SLURM, RAY "TRAINING"
The homogeneous compute shape of a cluster. Every pod in the cluster is identical: podCount pods, each with gpuCountPerPod GPUs of type gpuTypeId. Total GPUs = podCount * gpuCountPerPod.
A lightweight summary of a cluster's member pods. Use GET /v2/clusters/{id}/pods to retrieve the full pod objects.
"2026-06-29T20:00:00Z"
ID of the template this cluster's pods were created from; omitted when they were not created from one.
"tpl_abc"
Data center the cluster is placed in (a cluster is always within a single data center). Derived from the member pods; omitted until at least one pod is placed.
"US-TX-3"
The cluster's overlay network; omitted until the network is provisioned.
The primary (master) node; omitted until a primary pod is placed. Its sshEndpoint is omitted until that pod is RUNNING with SSH exposed.