Create a cluster

Create a multi-node Runpod Cluster with a consistent compute shape and container configuration across every member Pod.

POST /v2/clusters

Create a cluster

cURL

curl --request POST \
  --url https://api.runpod.io/v2/clusters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "compute": {
    "gpuTypeId": "NVIDIA H100 80GB HBM3",
    "gpuCountPerPod": 8,
    "podCount": 4
  },
  "name": "my-training-cluster",
  "type": "TRAINING",
  "args": "--model meta-llama/Llama-3-8B --max-model-len 8192",
  "cmd": [
    "--model",
    "meta-llama/Llama-3-8B",
    "--max-model-len",
    "8192"
  ],
  "entrypoint": [
    "/bin/bash",
    "-c"
  ],
  "disk": 50,
  "env": {
    "JUPYTER_PASSWORD": "hunter2"
  },
  "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "templateId": "30zmvf89kd",
  "dataCenterIds": [
    "US-TX-3"
  ],
  "mounts": {
    "network": [
      {
        "volumeId": "vol_xyz",
        "path": "/runpod-volume"
      }
    ]
  },
  "startJupyter": false,
  "startSsh": false
}
'

201

{
  "id": "cluster_abc123",
  "name": "my-training-cluster",
  "type": "TRAINING",
  "compute": {
    "gpuTypeId": "NVIDIA H100 80GB HBM3",
    "gpuCountPerPod": 8,
    "podCount": 4
  },
  "pods": {
    "total": 4,
    "byStatus": {
      "RUNNING": 3,
      "PROVISIONING": 1
    }
  },
  "createdAt": "2026-06-29T20:00:00Z",
  "template": "tpl_abc",
  "dataCenterId": "US-TX-3",
  "network": {
    "cidr": "10.65.0.0/16",
    "vxlanId": 42,
    "vxlanPort": 4789
  },
  "primary": {
    "podId": "pod_node0",
    "status": "PROVISIONING",
    "sshEndpoint": "1.2.3.4:22001"
  }
}

Authorizations

Authorization · string · header · required

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

application/json

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).

compute · object · required

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.

Show child attributes

name · string · required

Minimum string length: 1

Example:

"my-training-cluster"

type · enum<string> · required

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.

Available options: APPLICATION, TRAINING, SLURM, RAY

Example:

"TRAINING"

args · string

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.

Examples:

"--model meta-llama/Llama-3-8B --max-model-len 8192"

"{\"entrypoint\":[\"/bin/bash\",\"-c\"],\"cmd\":[\"python -u main.py\"]}"

""

cmd · string[]

Container CMD in exec form. When the image defines an ENTRYPOINT, this is the argument list passed to it. Encoded into the args field; supplying both is allowed only when they describe the same command. Send [] to clear, omit to leave unchanged.

Example:

[
  "--model",
  "meta-llama/Llama-3-8B",
  "--max-model-len",
  "8192"
]

entrypoint · string[]

Container ENTRYPOINT in exec form, overriding the image's own. Encoded into args field; supplying both is allowed only when they describe the same command. Send [] to clear, omit to leave unchanged.

Example:

["/bin/bash", "-c"]

disk · integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

env · object

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

image · string

Docker image reference

Example:

"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404"

ports · string[]

Exposed ports, formatted as port/protocol

Example:

["8888/http", "22/tcp"]

templateId · string

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, ports, and mounts (rejected with 400). The cluster retains the link: the template response field is set. Must be a non-serverless pod template accessible to the caller.

Minimum string length: 1

Example:

"30zmvf89kd"

dataCenterIds · string[]

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.

Example:

["US-TX-3"]

mounts · object

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 mounts or 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 volumeId of a network mount is immutable; a PATCH that names a different volumeId is rejected with 400.
• Partial mounts are not supported — every mount entry must include the full schema (size + path for persistent, volumeId + path for network). Missing required fields → 422.

Show child attributes

startJupyter · boolean · default: false

Start Jupyter on every member pod, as on pod create.

startSsh · boolean · default: false

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.

Response

201

application/json

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.

id · string · required

Example:

"cluster_abc123"

name · string · required

Example:

"my-training-cluster"

type · enum<string> · required

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.

Available options: APPLICATION, TRAINING, SLURM, RAY

Example:

"TRAINING"

compute · object · required

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.

Show child attributes

pods · object · required

A lightweight summary of a cluster's member pods. Use GET /v2/clusters/{id}/pods to retrieve the full pod objects.

Show child attributes

createdAt · string<date-time> · required

Example:

"2026-06-29T20:00:00Z"

template · string

ID of the template this cluster's pods were created from; omitted when they were not created from one.

Example:

"tpl_abc"

dataCenterId · string

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.

Example:

"US-TX-3"

network · object

The cluster's overlay network; omitted until the network is provisioned.

Show child attributes

primary · object

The primary (master) node; omitted until a primary pod is placed. Its sshEndpoint is omitted until that pod is RUNNING with SSH exposed.

Show child attributes