Create a cluster

POST

clusters

Create a cluster

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
}
'

import requests

url = "https://api.runpod.io/v2/clusters"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.runpod.io/v2/clusters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.runpod.io/v2/clusters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runpod.io/v2/clusters"

	payload := strings.NewReader("{\n  \"compute\": {\n    \"gpuTypeId\": \"NVIDIA H100 80GB HBM3\",\n    \"gpuCountPerPod\": 8,\n    \"podCount\": 4\n  },\n  \"name\": \"my-training-cluster\",\n  \"type\": \"TRAINING\",\n  \"args\": \"--model meta-llama/Llama-3-8B --max-model-len 8192\",\n  \"cmd\": [\n    \"--model\",\n    \"meta-llama/Llama-3-8B\",\n    \"--max-model-len\",\n    \"8192\"\n  ],\n  \"entrypoint\": [\n    \"/bin/bash\",\n    \"-c\"\n  ],\n  \"disk\": 50,\n  \"env\": {\n    \"JUPYTER_PASSWORD\": \"hunter2\"\n  },\n  \"image\": \"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404\",\n  \"ports\": [\n    \"8888/http\",\n    \"22/tcp\"\n  ],\n  \"templateId\": \"30zmvf89kd\",\n  \"dataCenterIds\": [\n    \"US-TX-3\"\n  ],\n  \"mounts\": {\n    \"network\": [\n      {\n        \"volumeId\": \"vol_xyz\",\n        \"path\": \"/runpod-volume\"\n      }\n    ]\n  },\n  \"startJupyter\": false,\n  \"startSsh\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/clusters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

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

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

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, …) 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 for a cluster create: persistent or network, not both. Clusters cannot mount global volumes, so global is rejected with 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

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.

string

required

Example:

"cluster_abc123"

name

string

required

Example:

"my-training-cluster"

type

enum<string>

required

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

Last modified on September 17, 2026

Create a cluster

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
}
'

import requests

url = "https://api.runpod.io/v2/clusters"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.runpod.io/v2/clusters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.runpod.io/v2/clusters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runpod.io/v2/clusters"

	payload := strings.NewReader("{\n  \"compute\": {\n    \"gpuTypeId\": \"NVIDIA H100 80GB HBM3\",\n    \"gpuCountPerPod\": 8,\n    \"podCount\": 4\n  },\n  \"name\": \"my-training-cluster\",\n  \"type\": \"TRAINING\",\n  \"args\": \"--model meta-llama/Llama-3-8B --max-model-len 8192\",\n  \"cmd\": [\n    \"--model\",\n    \"meta-llama/Llama-3-8B\",\n    \"--max-model-len\",\n    \"8192\"\n  ],\n  \"entrypoint\": [\n    \"/bin/bash\",\n    \"-c\"\n  ],\n  \"disk\": 50,\n  \"env\": {\n    \"JUPYTER_PASSWORD\": \"hunter2\"\n  },\n  \"image\": \"runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404\",\n  \"ports\": [\n    \"8888/http\",\n    \"22/tcp\"\n  ],\n  \"templateId\": \"30zmvf89kd\",\n  \"dataCenterIds\": [\n    \"US-TX-3\"\n  ],\n  \"mounts\": {\n    \"network\": [\n      {\n        \"volumeId\": \"vol_xyz\",\n        \"path\": \"/runpod-volume\"\n      }\n    ]\n  },\n  \"startJupyter\": false,\n  \"startSsh\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/clusters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

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

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

API v2

Organization

Account

Pods

Clusters

Serverless

Templates

Network Volumes

Global Volumes

Registries

Catalog

Billing

Authorizations

Body

Response