Get a pod

Returns a single pod by ID.

GET /v2/pods/{id}

Get a pod

cURL

curl --request GET \
  --url https://api.runpod.io/v2/pods/{id} \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.runpod.io/v2/pods/{id}")
  .header("Authorization", "Bearer <token>")
  .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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

200

{
  "id": "7h9k2m4n6p",
  "name": "pytorch-training",
  "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": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

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

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

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