Update a pod

Partially updates a pod’s configuration. This is a PATCH: only the fields present in the body are changed, and omitted fields are left untouched. Use empty values only when you explicitly mean to clear a field (for example, set registry to null or set ports to []). See UpdatePodRequest for the full body.

Mutable fields: name, image, args, disk, ports, env, registry, mounts, locked, and globalNetworking. Some changes apply immediately while others (e.g. globalNetworking) take effect on the pod’s next start/restart, as noted on the individual fields.

Returns 200 with the full updated pod.

PATCH /v2/pods/{id}

Update a pod

cURL

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

import requests

url = "https://api.runpod.io/v2/pods/{id}"

payload = { "name": "renamed-training-pod" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'renamed-training-pod'})
};

fetch('https://api.runpod.io/v2/pods/{id}', 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/pods/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'renamed-training-pod'
  ]),
  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/pods/{id}"

	payload := strings.NewReader("{\n  \"name\": \"renamed-training-pod\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.runpod.io/v2/pods/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"renamed-training-pod\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.runpod.io/v2/pods/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"renamed-training-pod\"\n}"

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

200

{
  "id": "7h9k2m4n6p",
  "name": "renamed-training-pod",
  "image": "runpod/pytorch:2.8.0-py3.11-cuda12.8.1",
  "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
  },
  "cloud": "SECURE",
  "dataCenterId": "US-KS-2",
  "template": "9x4m2p7v",
  "cost": 0.44,
  "locked": false,
  "globalNetworking": {
    "enabled": false
  },
  "runtime": {
    "uptime": 3600
  },
  "createdAt": "2026-06-01T12:00:00Z",
  "startedAt": "2026-06-01T12:02:00Z"
}

{
  "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": "Not Found",
  "status": 404,
  "detail": "resource not found"
}

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

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

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "errors": [
    "<string>"
  ]
}

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.

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

Available options: SECURE, COMMUNITY

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

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