Update a pod

Update selected settings on an existing Runpod Pod while preserving omitted fields, with guidance on mutable fields and restart behavior.

PATCH /v2/pods/{id}

cURL

renamePod

curl --request PATCH \ --url https://api.runpod.io/v2/pods/{id} \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "name": "renamed-training-pod" } '

200

{
  "id": "7h9k2m4n6p",
  "name": "renamed-training-pod",
  "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": "RUNNING",
  "actions": [
    "stop",
    "restart",
    "terminate"
  ],
  "mounts": {
    "persistent": {
      "size": 20,
      "path": "/workspace"
    }
  },
  "gpu": {
    "id": "NVIDIA GeForce RTX 4090",
    "count": 1,
    "vcpuCount": 16,
    "memory": 64
  },
  "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": {
      "host": "195.26.233.3",
      "port": 34446,
      "username": "root",
      "command": "ssh root@195.26.233.3 -p 34446"
    }
  },
  "template": "9x4m2p7v",
  "cost": 0.44,
  "locked": false,
  "globalNetworking": {
    "enabled": false
  },
  "runtime": {
    "uptime": 3600,
    "ports": [
      {
        "private": 22,
        "public": 34446,
        "type": "tcp",
        "ip": "195.26.233.3"
      }
    ]
  },
  "createdAt": "2026-06-01T12:00:00Z",
  "startedAt": "2026-06-01T12:02:00Z"
}

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.

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.

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

registry · string | null

Container registry credential ID (for private images)

Example:

null

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. See GET /v2/catalog/datacenters (globalNetwork) for eligible data centers.

locked · boolean

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

mounts · object

Changes to a pod's mounts. Each entry names one volume by volumeId and changes only that volume; volumes that are not listed, and kinds that are omitted, are left as they are. Omitting mounts or sending {} changes nothing.

• A listed volume the pod does not have is mounted at path.
• A listed volume the pod already has moves to path (or stays put when path is omitted).
• remove: true unmounts the volume. It cannot be combined with path, and the volume must be mounted on the pod.
• To swap a volume, remove the old one and add the new one in the same request.

Limits are checked against the pod as it would be after the request and rejected with 400: at most 4 network volumes and 1 global volume, and a volume disk cannot share a pod with network or global volumes. A volume disk can be added to a pod that has no volumes mounted (or unmounts them all in the same request), and it can only grow. Removing a volume disk is not supported yet.

Show child attributes

name · string

Minimum string length: 1

templateId · string

ID of a pod template whose container settings are applied as if they were provided in this PATCH body (image, args, disk, ports, env, registry — mounts are not applied on update). Explicit body fields override the template's; env merges template and body per key (body wins) and, per PATCH semantics, replaces the pod's env. One-time application — no link to the template is retained. Must be one of your templates or a public template (unknown or inaccessible ID → 404); must not be a serverless template (→ 422).

Example:

"30zmvf89kd"

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.

args · string · required

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

""

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. persistent (the volume disk) is mutually exclusive with both network and global (enforced at the handler with 400 if combined). A pod takes up to 4 network volumes and 1 global volume. Every network volume must be in the pod's data center, each volume may be listed once, and mount paths must not overlap; a request that breaks one of these is rejected. To change a pod's mounts after creation, see UpdatePodMounts.

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

The pod's hourly compute rate in USD. It's returned in every status, including EXITED, so it isn't what you're paying right now: a stopped pod isn't billed for compute, only for its volume disk.

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, and when listing pods with GET /v2/pods; fetch a single pod by ID to obtain metrics.

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"

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

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.

Show child attributes

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.

Show child attributes

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