> This page is for Self-Hosted, version v3.0 (default). > For other versions, use one of these documentation indexes: > - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt > - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt > - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt > - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server. # Get workload pods by id. GET http://localhost:8080/api/v1/workloads/{workloadId}/pods Retrieve the details of workload pods by workload id. Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/workloads/pods/get-workload-pods ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication ## Request ### Path parameters - `workloadId` (string, required) — The Universally Unique Identifier (UUID) of the workload. ### Query parameters - `deleted` (boolean, optional) — Return only deleted resources when `true`. - `offset` (integer, optional) — The offset of the first item returned in the collection. - `limit` (integer, optional, default: 50) — The maximum number of entries to return. - `search` (string, optional) — Filter results by a free text search. - `sortOrder` (enum, optional, default: asc) — Sort results in descending or ascending order. - Allowed values: `asc`, `desc` - `sortBy` (enum, optional) — Sort results using a parameter. - Allowed values: `name`, `clusterId`, `workloadId`, `revisionId`, `nodeName`, `currentNodepool`, `task`, `createdAt`, `completedAt`, `deletedAt` - `filterBy` (list of string, optional) — Filter results using a parameter. Use the format field-name operator value. Operators are `==` Equals, `!=` Not equals, `<=` Less than or equal, `>=` Greater than or equal, `=@` contains, `!@` Does not contains, `=^` Starts with and `=$` Ends with. Dates are in ISO 8601 timestamp format and available for operators `==`, `!=`, `<=` and `>=`. ## Response ### 200 Executed successfully. - `pods` (list of Pod, required) - `next` (integer, optional) ## Errors ### 401 Unauthorized Error Unauthorized - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 403 Forbidden Error Forbidden - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 404 Not Found Error The specified resource was not found - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 500 Internal Server Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 503 Service Unavailable Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ## Types ### Pod - `name` (string, required) - `priorityClassName` (string, required) - `id` (string, required) - `workloadId` (string, required) - `clusterId` (string, required) — The id of the cluster. - `createdAt` (datetime, required) - `containers` (list of Container, required) - `k8sPhase` (string, required) - `tenantId` (integer, required) — The id of the tenant. - `k8sPhaseUpdatedAt` (datetime, required) - `updatedAt` (datetime, required) - `revisionId` (string, optional, nullable) - `projectId` (string, optional) - `nodeName` (string, optional, nullable) - `completedAt` (datetime, optional, nullable) - `currentNodePool` (string, optional, nullable) - `requestedNodePools` (list of string, optional) - `requestedResources` (PodRequestResources, optional) - `allocatedResources` (AllocatedResources, optional) - `tolerations` (list of PodToleration, optional) - `ip` (string, optional, nullable) - `task` (string, optional, nullable) — Identifies the function of the pod within a distributed workload (for example, leader, worker, or master). - `nodeAffinity` (PodNodeAffinity, optional) — group of node affinity scheduling rules. - `elements` (list of PodElement, optional, nullable) — The workload structure elements this pod belongs to, ordered by hierarchy level. - `deletedAt` (datetime, optional, nullable) - `projectName` (string, optional) - `workloadName` (string, optional) ### Container - `name` (string, required) - `image` (string, required) - `startedAt` (datetime, optional, nullable) ### PodRequestResources - `gpuRequestType` (enum, optional) — Sets the unit type for GPU resources requests. Stated in terms of portion or memory. Sets the unit type for other GPU request fields. If `gpuDevicesRequest > 1`, only `portion` is supported. If `gpuDeviceRequest = 1`, the request type can be stated as `portion` or `memory`. - Allowed values: `portion`, `memory` - `gpu` (RequestResourceCores, optional) - `gpuMemory` (RequestResourceQuantity, optional) - `cpu` (RequestResourceCores, optional) - `cpuMemory` (RequestResourceQuantity, optional) - `extendedResources` (list of WorkloadsExtendedResource, optional) — Set of extended resources with their quantity ### AllocatedResources - `gpu` (double, optional, nullable) — Required if and only if gpuRequestType is portion. States the number of GPUs allocated for the created workload. The default is no allocated GPUs. - `gpuMemory` (string, optional, nullable) - `cpu` (double, optional, nullable) — States the amount of CPU cores used by the workload running. - `cpuMemory` (string, optional, nullable) - `extendedResources` (list of WorkloadsExtendedResource, optional) — Set of extended resources with their quantity ### PodToleration - `key` (string, optional) — Key is the taint key that the toleration applies to. Empty means match all taint keys. - `operator` (string, optional) — Operator represents a key's relationship to the value. - `value` (string, optional) — Value is the taint value the toleration matches to. - `effect` (string, optional) — Effect indicates the taint effect to match. Empty means match all taint effects. - `tolerationSeconds` (integer, optional, nullable) — TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. ### PodNodeAffinity group of node affinity scheduling rules. - `required` (PodNodeAffinityRequired, optional, nullable) — If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - `preferred` (PodNodeAffinityPreferred, optional, nullable) — The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. ### PodElement - `elementId` (string, required) — The unique identifier of the workload structure element this pod is associated with. - `hierarchyLevel` (integer, required) — The hierarchy level of this pod's associated workload structure element. Level 1 represents the top of the hierarchy, with levels 2 and 3 representing progressively nested elements. ### RequestResourceCores - `limit` (double, optional, nullable) - `request` (double, optional, nullable) ### RequestResourceQuantity - `limit` (string, optional, nullable) - `request` (string, optional, nullable) ### WorkloadsExtendedResource Quantity of an extended resource. - `resource` (string, optional, nullable) — The name of the extended resource (mandatory) - `quantity` (string, optional, nullable) — The requested quantity for the given resource. - `exclude` (boolean, optional, nullable) — Whether to exclude this extended resource from the workload. This is necessary in case the extended resource is inherited from the policy defaults and it is desired not to include it in this workload. ### PodNodeAffinityRequired If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - `nodeSelectorTerms` (list of NodeSelectorTerm, optional) — A list of node selector terms. The terms are ORed. ### PodNodeAffinityPreferred The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - `nodeSelectorTerms` (list of PodPreferredNodeSelectorTerm, optional) — A list of node selector terms. ### NodeSelectorTerm A null or empty node selector term matches no objects. The requirements of them are ANDed. - `matchExpressions` (list of MatchExpression, optional) — A list of node selector requirements by node's labels. ### PodPreferredNodeSelectorTerm An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - `weight` (double, optional) — Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - `preference` (NodeSelectorTerm, optional) — A null or empty node selector term matches no objects. The requirements of them are ANDed. ### MatchExpression A selector that contains values, a key, and an operator that relates the key and values. - `key` (string, required) — The label key that the selector applies to (mandatory). - `operator` (enum, required) — Represents a key's relationship to a set of values (mandatory). - Allowed values: `In`, `NotIn`, `Exists`, `DoesNotExist`, `Gt`, `Lt` - `values` (list of string, optional) — An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. ## Examples **Response** ```json { "pods": [ { "name": "pod-of-a-very-important-job", "priorityClassName": "high-priority", "id": "string", "workloadId": "string", "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210", "createdAt": "2022-01-01T03:49:52.531Z", "containers": [ { "name": "alpine", "image": "alpine:latest", "startedAt": "2022-01-01T03:49:52.531Z" } ], "k8sPhase": "Pending", "tenantId": 1001, "k8sPhaseUpdatedAt": "2022-06-08T11:28:24.131Z", "updatedAt": "2022-06-08T11:28:24.131Z", "revisionId": "string", "projectId": "1", "nodeName": "gpu-node-1", "completedAt": "2022-01-01T03:49:52.531Z", "currentNodePool": "default", "requestedNodePools": [ "default" ], "requestedResources": { "gpuRequestType": "portion", "gpu": { "limit": 1.5, "request": 1 }, "gpuMemory": { "limit": "2G", "request": "200M" }, "cpu": { "limit": 1.5, "request": 1 }, "cpuMemory": { "limit": "2G", "request": "200M" }, "extendedResources": [ { "resource": "hardware-vendor.example/foo", "quantity": "2", "exclude": false } ] }, "allocatedResources": { "gpu": 1.5, "gpuMemory": "200Mi", "cpu": 0.5, "cpuMemory": "0B", "extendedResources": [ { "resource": "hardware-vendor.example/foo", "quantity": "2", "exclude": false } ] }, "tolerations": [ { "key": "", "operator": "Exists", "value": "", "effect": "NoExecute", "tolerationSeconds": 10 } ], "ip": "10.244.1.1", "task": "leader", "nodeAffinity": { "required": { "nodeSelectorTerms": [ { "matchExpressions": [ { "key": "string", "operator": "In", "values": [ "string" ] } ] } ] }, "preferred": { "nodeSelectorTerms": [ { "weight": 1.1, "preference": { "matchExpressions": [ { "key": "string", "operator": "In", "values": [ "string" ] } ] } } ] } }, "elements": [ { "elementId": "string", "hierarchyLevel": 1 } ], "deletedAt": "2022-08-12T19:28:24.131Z", "projectName": "my-project", "workloadName": "my-workload" } ], "next": 1 } ``` **SDK Code** ```python import requests url = "http://localhost:8080/api/v1/workloads/workloadId/pods" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'http://localhost:8080/api/v1/workloads/workloadId/pods'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "http://localhost:8080/api/v1/workloads/workloadId/pods" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("http://localhost:8080/api/v1/workloads/workloadId/pods") http = Net::HTTP.new(url.host, url.port) request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("http://localhost:8080/api/v1/workloads/workloadId/pods") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'http://localhost:8080/api/v1/workloads/workloadId/pods', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("http://localhost:8080/api/v1/workloads/workloadId/pods"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:8080/api/v1/workloads/workloadId/pods")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```