Skip to main content
POST
Create a cluster

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

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"

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.

image
string

Docker image reference

Example:

"runpod/pytorch:2.8.0-py3.11-cuda12.8.1"

args
string

Arguments passed to the container entrypoint

Example:

""

disk
integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1
Example:

50

ports
string[]

Exposed ports, formatted as port/protocol

Example:
env
object

Environment variables as key-value pairs

Example:
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.

startJupyter
boolean
default:false

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

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

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.

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.

pods
object
required

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

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.

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.