Create a cluster
Create a multi-node Runpod Cluster with a consistent compute shape and container configuration across every member Pod.
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.
Console sessions (Clerk JWTs) act for the signed-in user. To act for a team instead, also send X-Team-Id: <team_id>; it applies only when the user owns or belongs to that team, otherwise the request runs against the user's own account. API keys created inside a team already act for that team and do not need the header.
Body
Request body for creating a cluster. compute defines the
homogeneous pod shape; the container configuration (image, env, ports,
…) applies to every pod. Pass templateId to provision every member
pod from a pod template instead of inline container fields — the
template also supplies the container registry credential, the only
private-image path for clusters (a bare registry property on this
body is rejected).
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 container's command, as a single raw string. This is the field entrypoint and cmd encode into, exposed in its stored form.
Two shapes are accepted. A bare shell string is treated as CMD and split into arguments, which is what the console's "Container start command" field writes. A JSON object of the form {"entrypoint":[...],"cmd":[...]} sets either or both explicitly.
Responses always return both representations: args exactly as stored, plus the deconstructed entrypoint and cmd. Supplying args together with entrypoint or cmd is allowed only when they describe the same command, so a read-modify-write client can send back everything it received. Send "" to clear, omit to leave unchanged.
"--model meta-llama/Llama-3-8B --max-model-len 8192"
"{\"entrypoint\":[\"/bin/bash\",\"-c\"],\"cmd\":[\"python -u main.py\"]}"
""
ID of a pod template to provision every member pod from. The
template supplies the container settings (image, args, disk,
env, ports) and the container registry credential for private
images — the only private-image path for clusters. Mutually
exclusive with image, args, entrypoint, cmd, disk,
env, and ports (rejected with 400). mounts combines with
it: the volume in mounts is attached to every member pod,
overriding the template's volume settings. The cluster
retains the link: the template response field is set. Must be
a non-serverless pod template accessible to the caller.
1"30zmvf89kd"
Storage mounts for a cluster create: persistent or one network
volume, not both. Clusters cannot mount global volumes, so global
is rejected with 422. A mount path must not be empty (rejected with 422): an
empty path reads as unset and would mount the volume at the
template's path, or /workspace without a template.
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 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 tags on this resource that are visible to the caller. Keys and values are returned exactly as stored. Tags under the reserved runpod: prefix, such as the cost center, are never listed here. Absent when the resource's tags are unavailable to the caller; an empty array means none are visible.