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.

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

application/json

Request body for creating a cluster. compute defines the homogeneous pod shape; the container configuration (image, env, ports, registry, …) applies to every pod. Pass templateId to provision every member pod from a pod template instead of inline container fields. For a private image, pass registry (one of your credentials from /v2/registries); it is attached to every member pod, and an ID that does not exist or is not yours is a 400.

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.

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:
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:
disk
integer

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1
Example:

50

env
object

Environment variables as key-value pairs

Example:
image
string

Docker image reference

Example:

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

ports
string[]

Exposed ports, formatted as port/protocol

Example:
registry
string | null

Container registry credential ID for a private image: one of your credentials from /v2/registries. Leave it unset for a private Amazon ECR image. Runpod pulls those with an ECR delegation (/v2/registries/delegations) matched to the image's account, region and repository at pull time, so there is no delegation ID to pass here (a delegation ID is not a credential ID). A credential set here is used instead of any delegation.

Example:

null

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. Mutually exclusive with image, args, entrypoint, cmd, disk, env, and ports (rejected with 400). registry combines with it: an explicit registry overrides the template's credential; omit it (or send null or an empty string) to use the template's. mounts combines with it too: 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.

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:
mounts
object

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.

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

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"

costCenter
object

Cost center this resource's spend is attributed to. Absent when the resource is not attributed to a cost center, or when the caller lacks permission to view cost centers. Managed through /v2/cost-centers.

tags
object[]

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.

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.

Last modified on November 14, 2026