Create a pod

Creates a new pod. Specify gpu for compute. ContainerConfig fields can be spread from a template response.

POST /v2/pods

Error

A valid request URL is required to generate request examples

201

{
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "args": "",
  "disk": 50,
  "ports": [
    "8888/http",
    "22/tcp"
  ],
  "env": {
    "JUPYTER_PASSWORD": "hunter2"
  },
  "registry": null,
  "id": "pod_abc123",
  "name": "my-training-pod",
  "actions": [],
  "mounts": {
    "persistent": {
      "size": 20,
      "path": "/workspace"
    },
    "network": [
      {
        "volumeId": "vol_xyz",
        "path": "/runpod-volume"
      }
    ]
  },
  "dataCenterId": "US-TX-3",
  "template": null,
  "cost": 0.35,
  "locked": false,
  "globalNetworking": {
    "enabled": true,
    "ip": "10.65.1.42",
    "internalDns": "gfj8b292vyg08g.runpod.internal"
  },
  "tags": [
    {
      "id": "tag_abc123",
      "key": "project",
      "value": "gpt-training",
      "resources": [
        {
          "id": "pod_abc123",
          "type": "POD"
        }
      ]
    }
  ],
  "runtime": {
    "uptime": 3600,
    "gpus": [
      {
        "util": 94,
        "memoryUtil": 78
      }
    ],
    "cpu": {
      "util": 45
    },
    "memory": {
      "util": 45
    },
    "ports": [
      {
        "private": 8888,
        "public": 43210,
        "type": "http",
        "ip": "45.23.12.1"
      }
    ]
  },
  "createdAt": "2026-03-13T20:00:00Z",
  "startedAt": "2026-03-13T20:00:00Z",
  "gpu": {
    "id": "NVIDIA GeForce RTX 4090",
    "count": 1
  },
  "cpu": {
    "id": "cpu5c",
    "vcpuCount": 4,
    "memory": 16
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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 · string · required

Docker image reference

Example:

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

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

ports · string[]

Exposed ports, formatted as port/protocol

Example:

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

env · object

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

registry · string | null

Container registry credential ID (for private images)

Example:

null

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

gpu · object

Show child attributes

cpu · object

Show child attributes

cloud · enum<string>

Cloud tier.

• SECURE — RunPod-owned datacenter hardware
• COMMUNITY — community-hosted hardware
• ALL — eligible for either tier (request-only; responses always report the concrete tier the pod was placed on)

Available options: SECURE, COMMUNITY, ALL

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

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.

image · string · required

Docker image reference

Example:

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

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

ports · string[] · required

Exposed ports, formatted as port/protocol

Example:

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

env · object · required

Environment variables as key-value pairs

Show child attributes

Example:

{ "JUPYTER_PASSWORD": "hunter2" }

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
• ALL — eligible for either tier (request-only; responses always report the concrete tier the pod was placed on)

Available options: SECURE, COMMUNITY, ALL

dataCenterId · string | null · required

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

Example:

"US-TX-3"

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

tags · object[] · required

Tags attached to this pod.

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