Update a pod

Updates pod configuration. Only provided fields are changed.

PATCH /v2/pods/{id}

Error

A valid request URL is required to generate request examples

200

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

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found"
}

Authorizations

Authorization · string · header · required

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

Path Parameters

id · string · required

Pod identifier

Body

application/json

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

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:

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

name · string

Minimum string length: 1

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

locked · boolean

Lock the pod (true) or unlock it (false). Locked pods cannot be stopped or reset.

globalNetworking · boolean

Enable (true) or disable (false) global networking. Takes effect on the next pod start/restart, not live. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See GET /v2/catalog/datacenters (globalNetwork) for eligible data centers.

Response

200

application/json

OK

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