Create a pod

Creates a new pod. name is always required; supply exactly one of gpu or cpu to select compute (a GPU or a CPU pod). Container settings come from the body, from a template referenced by templateId (body fields override the template’s), or both; image is required unless templateId is set. See CreatePodRequest for the full body.

Returns 201 with the created pod. Provisioning is asynchronous: the pod starts in PROVISIONING, transitions through STARTING, and reaches RUNNING once its container is healthy. Poll getPod (or watch the pod’s status) to observe readiness rather than assuming the pod is running when this call returns.

Checking what you can deploy

This endpoint places one specific GPU type. It does not search for capacity, and it does not fall back to a different GPU. To find out what is deployable before you call it, read the catalog:

• List GPU types — GPU types with pricing, per-cloud ceilings, and, with include=AVAILABILITY&product=POD, current pod stock.
• List data centers — locations, with include=GPU_AVAILABILITY for stock per data center.

Both accept filters that combine, so you can narrow by location and by compute in one request — for example GET /v2/catalog/datacenters?regions=EUROPE&include=GPU_AVAILABILITY returns only European data centers, each carrying the GPU types currently available there.

Deploying under region and GPU constraints

If you need a particular GPU in a particular geography, the working pattern is read-then-create: narrow the catalog to an acceptable (data center, GPU) set, then call this endpoint once per candidate in your order of preference until one returns 201. The runnable sample alongside this operation does exactly that.

Availability can change between the catalog read and the create call, so treat the catalog as a way to order your candidates, not as a reservation — a create can still fail for capacity on a GPU the catalog just reported as available.

Which failures are worth retrying:

Status	Meaning	Do
422	The body does not match the contract. errors lists each violation.	Fix the request. Never retry.
400	The body matches the contract but was rejected — either it breaks a cross-field rule, or this GPU and data center combination could not be placed.	Try your next candidate.
402	Insufficient balance.	Stop; no candidate will succeed.
403	Your account cannot access the requested pool.	Skip this candidate, keep going.
429	Rate limited.	Back off using Retry-After, then resume.
5xx	Transient upstream failure.	Retry the same candidate with backoff.

400 covers both “your request breaks a rule” and “no capacity”, because capacity exhaustion currently carries no machine-readable code of its own — only a human-readable detail. A rule violation is deterministic, so it fails identically on every candidate: if every candidate returns 400, read the last detail as a problem with the request rather than as absent capacity.

POST /v2/pods

Region-constrained deploy loop

Python

import os
import time

import requests

API = "https://api.runpod.io"
SESSION = requests.Session()
SESSION.headers["Authorization"] = f"Bearer {os.environ['RUNPOD_API_KEY']}"

# Most preferred GPU first. The loop stops at the first one that places.
GPU_PREFERENCE = [
    "NVIDIA GeForce RTX 4090",
    "NVIDIA GeForce RTX 5090",
    "NVIDIA H100 PCIe",
]
USABLE = {"LOW", "MEDIUM", "HIGH"}  # anything but NONE


def candidates(region):
    """(gpu_id, datacenter_id) pairs that the catalog reports as deployable,
    ordered by GPU_PREFERENCE then by descending stock."""
    response = SESSION.get(
        f"{API}/v2/catalog/datacenters",
        params={"regions": region, "include": "GPU_AVAILABILITY"},
        timeout=30,
    )
    response.raise_for_status()

    rank = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
    found = []
    for datacenter in response.json()["dataCenters"]:
        for gpu in datacenter.get("gpuAvailability", []):
            if gpu["id"] in GPU_PREFERENCE and gpu["availability"] in USABLE:
                found.append((gpu["id"], datacenter["id"], gpu["availability"]))

    found.sort(key=lambda c: (GPU_PREFERENCE.index(c[0]), rank[c[2]]))
    return [(gpu_id, dc_id) for gpu_id, dc_id, _ in found]


def create(gpu_id, datacenter_id):
    return SESSION.post(
        f"{API}/v2/pods",
        json={
            "name": "inference-worker",
            "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
            "gpu": {"id": gpu_id, "count": 1},
            "dataCenterIds": [datacenter_id],
            "disk": 50,
        },
        timeout=60,
    )


def create_with_backoff(gpu_id, datacenter_id, attempts=5):
    """Rate limits and 5xx are not the candidate's fault, so they are
    retried in place rather than moving to the next GPU."""
    for attempt in range(attempts):
        response = create(gpu_id, datacenter_id)
        if response.status_code == 429:
            # Retry-After is integer seconds on this API.
            time.sleep(int(response.headers.get("Retry-After", 5)))
            continue
        if response.status_code >= 500:
            time.sleep(2**attempt)
            continue
        return response
    raise RuntimeError(f"{attempts} transient failures for {gpu_id}; upstream unhealthy")


def deploy(region="EUROPE"):
    last_detail = None

    for gpu_id, datacenter_id in candidates(region):
        response = create_with_backoff(gpu_id, datacenter_id)

        if response.status_code == 201:
            return response.json()

        problem = response.json()
        last_detail = problem.get("detail")

        if response.status_code == 422:
            # Contract violation — identical on every candidate.
            raise SystemExit(f"Bad request: {problem.get('errors', last_detail)}")
        if response.status_code == 402:
            raise SystemExit(f"Cannot deploy: {last_detail}")
        if response.status_code in (400, 403):
            # 403: no access to this pool. 400: rule violation, or this
            # GPU/data center could not be placed. Either way, move on.
            continue

        response.raise_for_status()

    # Every candidate was refused. A rule violation fails the same way on
    # all of them, so the last detail is the useful signal here.
    raise SystemExit(f"No candidate placed in {region}. Last error: {last_detail}")


if __name__ == "__main__":
    pod = deploy()
    print(f"{pod['id']} placed in {pod['dataCenterId']} on {pod['gpu']['id']}")

201

{
  "id": "7h9k2m4n6p",
  "name": "pytorch-training",
  "image": "runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404",
  "args": "",
  "disk": 50,
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "env": {
    "MODEL_NAME": "llama-3"
  },
  "registry": null,
  "status": "PROVISIONING",
  "actions": [
    "start",
    "terminate"
  ],
  "mounts": {
    "persistent": {
      "size": 20,
      "path": "/workspace"
    }
  },
  "gpu": {
    "id": "NVIDIA GeForce RTX 4090",
    "count": 1
  },
  "cloud": "SECURE",
  "dataCenterId": "US-KS-2",
  "cudaVersion": "12.8",
  "ssh": {
    "proxy": {
      "host": "ssh.runpod.io",
      "port": 22,
      "username": "7h9k2m4n6p-64411eb2",
      "command": "ssh [e-mail]"
    },
    "direct": null
  },
  "template": "9x4m2p7v",
  "cost": 0.44,
  "locked": false,
  "globalNetworking": {
    "enabled": false
  },
  "runtime": {},
  "createdAt": "2026-06-01T12:00:00Z",
  "startedAt": null
}

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 pod. Exactly one of gpu or cpu must be set — enforced at the handler layer. For CPU pods, memory is derived by the API from the selected flavor's RAM multiplier; clients provide only CPU flavor and vCPU count. CPU pods support container disk and network volumes only; mounts.persistent is invalid when cpu is set.

image is required unless templateId is set.

name · string · required

Minimum string length: 1

Example:

"my-training-pod"

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

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"]

registry · string | null

Container registry credential ID (for private images)

Example:

null

cloud · enum<string> · default: SECURE

Cloud tier. Defaults to SECURE when omitted.

Available options: SECURE, COMMUNITY

cpu · object

Show child attributes

dataCenterIds · string[]

Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose.

Example:

["US-TX-3"]

globalNetworking · boolean · default: false

Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See GET /v2/catalog/datacenters (globalNetwork) for eligible data centers.

Example:

false

gpu · object

GPU request for a pod create. Carries the CUDA host constraints, which live here rather than at the body's top level so they are unrepresentable on a CPU pod.

Show child attributes

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

Create-time flag telling the provisioner to start JupyterLab: injects a generated JUPYTER_PASSWORD environment variable, unless the request already sets one. Only images that honor the convention start Jupyter from it (RunPod official images do); expose 8888/http in ports to reach it.

Not part of the pod's readable config — never returned by GET and not changeable by PATCH.

Example:

true

startSsh · boolean · default: false

Create-time flag telling the provisioner to set up SSH access: injects a PUBLIC_KEY environment variable carrying your account's registered SSH public keys, unless the request already sets one. Requires registered keys (PUT /v2/account/ssh-keys) — with none registered the flag does nothing and the pod has no SSH access. Only images that honor the convention start sshd from it (all RunPod official images do). Connect using the pod's ssh block; the ssh.direct variant additionally needs a 22/tcp entry in ports.

Not part of the pod's readable config — never returned by GET and not changeable by PATCH.

Example:

true

templateId · string

ID of a pod template to base this pod on. The template is resolved at create time into the same container settings you could otherwise spread into this body (image, args, disk, ports, env, registry, persistent mount, startSsh, startJupyter, allowedCudaVersions); explicit body fields override the template's, except env, which is merged per key with body values winning. Sending either CUDA field (gpu.allowedCudaVersions or gpu.minCudaVersion) replaces the template's CUDA constraint entirely, and CPU pods ignore it (like the persistent mount). The template is a one-time source of settings: later template edits do not affect the pod, and the created pod does not retain a link to the template (template stays null). The template may be one of your own or a public catalog template — see GET /v2/catalog/templates (unknown or inaccessible ID → 404) — and must not be a serverless template (→ 422). CPU pods do not inherit a template's persistent mount.

Minimum string length: 1

Example:

"30zmvf89kd"

Response

201

application/json

Created

Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources.

args · string · required

Arguments passed to the container entrypoint

Example:

""

disk · integer · required

Container disk in GB (ephemeral, wiped on restart)

Required range: x >= 1

Example:

50

env · object · required

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

image · string · required

Docker image reference

Example:

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

ports · string[] · required

Exposed ports, formatted as port/protocol

Example:

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

registry · string | null · required

Container registry credential ID (for private images)

Example:

null

id · string · required

Example:

"pod_abc123"

name · string · required

Example:

"my-training-pod"

status · enum<string> · required

Lifecycle status of a pod.

• PROVISIONING — pod is being allocated
• STARTING — container is starting
• RUNNING — container is healthy
• EXITED — container exited (stopped)
• ERROR — container is in an unrecoverable error state
• TERMINATED — pod has been permanently deleted

Available options: PROVISIONING, STARTING, RUNNING, EXITED, ERROR, TERMINATED

actions · enum<string>[] · required

Valid state transitions for the current status.

State transition to trigger on a pod.

Available options: start, stop, restart, terminate

mounts · object · required

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

cloud · enum<string> · required

Cloud tier.

• SECURE — Runpod-owned datacenter hardware
• COMMUNITY — community-hosted hardware

Available options: SECURE, COMMUNITY

dataCenterId · string | null · required

Data center where the pod is running (assigned by scheduler)

Example:

"US-TX-3"

cudaVersion · string | null · required

CUDA version reported by the host machine. Retained while the pod is stopped — a stopped pod keeps its machine assignment and resumes onto the same host. Null means unknown or not applicable (CPU pods, or a host that has not reported one), not that CUDA is absent.

Example:

"12.8"

ssh · object · required

SSH connection details, via the Runpod proxy or directly to the pod's published 22/tcp port.

Show child attributes

template · string | null · required

ID of the template this pod was created from

Example:

null

cost · number<float> · required

Current cost in USD per hour (0.0 when EXITED or TERMINATED)

Example:

0.35

locked · boolean · required

Whether the pod is locked (prevents stopping or resetting)

Example:

false

globalNetworking · object · required

Show child attributes

runtime · object | null · required

Live utilization metrics. Null when the pod is not RUNNING.

Show child attributes

createdAt · string<date-time> · required

Example:

"2026-03-13T20:00:00Z"

startedAt · string<date-time> | null · required

Example:

"2026-03-13T20:00:00Z"

gpu · object

Present for GPU pods; omitted from CPU pods.

Show child attributes

cpu · object

Present for CPU pods; omitted from GPU pods.

Show child attributes

cluster · object

Cluster membership; omitted from a standalone pod. Member pods are managed through /v2/clusters/{id} — they are excluded from GET /v2/pods by default (pass includeClusterPods=true to include them) and cannot be modified or deleted via the pod endpoints.

Show child attributes