Clusters
List a cluster's pods
Returns the full member pods of a cluster. The cluster summary (GET /v2/clusters/{id}) carries only aggregate pod counts; this endpoint returns each member as a complete Pod object.
GET
/
v2
/
clusters
/
{id}
/
pods
List a cluster's pods
curl --request GET \
--url https://api.runpod.io/v2/clusters/{id}/pods \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.runpod.io/v2/clusters/{id}/pods"
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/clusters/{id}/pods', 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/clusters/{id}/pods",
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/clusters/{id}/pods"
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/clusters/{id}/pods")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runpod.io/v2/clusters/{id}/pods")
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{
"pods": [
{
"image": "<string>",
"args": "<string>",
"disk": 2,
"ports": [
"<string>"
],
"env": {},
"registry": "<string>",
"id": "<string>",
"name": "<string>",
"actions": [],
"mounts": {
"persistent": {
"size": 11,
"path": "<string>"
},
"network": [
{
"volumeId": "<string>",
"path": "<string>"
}
]
},
"dataCenterId": "<string>",
"ssh": {
"proxy": {
"host": "<string>",
"port": 123,
"username": "<string>",
"command": "<string>"
},
"direct": {
"host": "<string>",
"port": 123,
"username": "<string>",
"command": "<string>"
}
},
"template": "<string>",
"cost": 123,
"locked": true,
"globalNetworking": {
"enabled": true,
"ip": "<string>",
"internalDns": "<string>"
},
"runtime": {
"uptime": 123,
"gpus": [
{
"util": 123,
"memoryUtil": 123
}
],
"cpu": {
"util": 123
},
"memory": {
"util": 123
},
"ports": [
{
"private": 123,
"public": 123,
"type": "<string>",
"ip": "<string>"
}
]
},
"createdAt": "2023-11-07T05:31:56Z",
"startedAt": "2023-11-07T05:31:56Z",
"gpu": {
"id": "<string>",
"count": 1
},
"cpu": {
"id": "<string>",
"vcpuCount": 3,
"memory": 2
},
"cudaVersion": "<string>",
"cluster": {
"id": "<string>",
"rank": 123,
"ip": "<string>"
}
}
]
}{
"title": "Unauthorized",
"status": 401,
"detail": "missing bearer token"
}{
"title": "Forbidden",
"status": 403,
"detail": "access denied"
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
"<string>"
]
}{
"title": "Too Many Requests",
"status": 429,
"detail": "rate limit exceeded for the minute window"
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
"<string>"
]
}Authorizations
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
Cluster identifier
Response
OK
Show child attributes
Show child attributes
Last modified on August 14, 2026
Was this page helpful?
⌘I
List a cluster's pods
curl --request GET \
--url https://api.runpod.io/v2/clusters/{id}/pods \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.runpod.io/v2/clusters/{id}/pods"
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/clusters/{id}/pods', 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/clusters/{id}/pods",
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/clusters/{id}/pods"
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/clusters/{id}/pods")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runpod.io/v2/clusters/{id}/pods")
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{
"pods": [
{
"image": "<string>",
"args": "<string>",
"disk": 2,
"ports": [
"<string>"
],
"env": {},
"registry": "<string>",
"id": "<string>",
"name": "<string>",
"actions": [],
"mounts": {
"persistent": {
"size": 11,
"path": "<string>"
},
"network": [
{
"volumeId": "<string>",
"path": "<string>"
}
]
},
"dataCenterId": "<string>",
"ssh": {
"proxy": {
"host": "<string>",
"port": 123,
"username": "<string>",
"command": "<string>"
},
"direct": {
"host": "<string>",
"port": 123,
"username": "<string>",
"command": "<string>"
}
},
"template": "<string>",
"cost": 123,
"locked": true,
"globalNetworking": {
"enabled": true,
"ip": "<string>",
"internalDns": "<string>"
},
"runtime": {
"uptime": 123,
"gpus": [
{
"util": 123,
"memoryUtil": 123
}
],
"cpu": {
"util": 123
},
"memory": {
"util": 123
},
"ports": [
{
"private": 123,
"public": 123,
"type": "<string>",
"ip": "<string>"
}
]
},
"createdAt": "2023-11-07T05:31:56Z",
"startedAt": "2023-11-07T05:31:56Z",
"gpu": {
"id": "<string>",
"count": 1
},
"cpu": {
"id": "<string>",
"vcpuCount": 3,
"memory": 2
},
"cudaVersion": "<string>",
"cluster": {
"id": "<string>",
"rank": 123,
"ip": "<string>"
}
}
]
}{
"title": "Unauthorized",
"status": 401,
"detail": "missing bearer token"
}{
"title": "Forbidden",
"status": 403,
"detail": "access denied"
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
"<string>"
]
}{
"title": "Too Many Requests",
"status": 429,
"detail": "rate limit exceeded for the minute window"
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
"<string>"
]
}