--- title: "How To: List the Pod Objects for a Kubernetes Cluster and Namespace" slug: "how-to-list-the-pod-objects-for-a-kubernetes-cluster-and-namespace" updated: 2026-07-09T11:56:55Z published: 2026-07-09T11:56:55Z canonical: "resources.realtheory.io/how-to-list-the-pod-objects-for-a-kubernetes-cluster-and-namespace" --- > ## Documentation Index > Fetch the complete documentation index at: https://resources.realtheory.io/llms.txt > Use this file to discover all available pages before exploring further. # How To: List the Pod Objects for a Kubernetes Cluster and Namespace After deploying the RealTheory collector to a Kubernetes cluster (See [Installing RealTheory in a Cluster](/v1/docs/installing-realtheory-in-a-cluster)), the cluster and its associated objects become available in the RealTheory API within minutes. ### Overview Listing the Kubernetes Pods for a given cluster and namespace is a three-step process, where each step resolves the identifiers needed by the next. All three calls are made against the [K8s](https://api-dev.realtheory.io/swagger/k8s/index.html) endpoint. 1. **Look up the cluster by name** using the `Clusters` endpoint with the query `metadata.name=<cluster-name>`. This gives the `<cluster-id>`. Example query: `metadata.name=realtheory-cluster-01` 2. **Get all namespaces associated with the cluster** using the `Namespaces` endpoint with the query `metadata.clusterId=<cluster-id>`. This gives all `<namespace-name>` and `<namespace-id>` values. Example query: `metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a` 3. **Look up the pods associated with the cluster and namespace** using the `Pods` endpoint with the query `metadata.clusterId=<cluster-id> AND metadata.namespaceId=<namespace-id>`. Example query: `metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a AND metadata.namespaceId=568490d7-9f0e-41ad-b416-8392056cb455` **Note:** - All calls to RealTheory APIs must be authenticated and authorized. See [Authentication](/v1/docs/authentication) for more details. - Each call accepts the common `index`, `count`, `order`, and `direction` paging parameters. See [Paging](/v1/docs/paging) for more details on how to page through all results. - Queries should be URL encoded; otherwise the request might be rejected. ### Step 1: Look up the cluster by name Call the method below to find the cluster whose name matches the given cluster name. ``` GET /theory/api/v1/k8s/clusters/search/query/{query}?index={index}&count={count}&order={order}&direction={direction} ``` where - `{endpoint}` - is the URL of the RealTheory SaaS portal for your account. - `{query}` - is a [query](/v1/docs/queries) used to match the cluster by name. - `{index}` - is the starting index of the clusters to include in the list. This parameter is optional and defaults to 0 if not specified. - `{count}` - is the maximum number of clusters to return, up to a limit of 500. This parameter is optional and defaults to 100 if not specified. - `{order}` - is a string containing the name of the attribute to sort on. This parameter is optional. - `{direction}` - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified. **Note:** While it is expected that the query will only return one result, the query may return more than one result if the cluster name is not unique. Page through the results as needed by incrementing the `{index}` by the `{count}` on each subsequent call. See [Paging](/v1/docs/paging) for more details. #### Example ``` GET theory/api/v1/k8s/clusters/search/query/metadata.name=realtheory-cluster-01?index=0&count=100&order=metadata.name&direction=0 ``` which returns the [Cluster](/v1/docs/k8s-cluster) objects whose name is `realtheory-cluster-01`. The `metadata.id` field of the returned object is the `<cluster-id>` used in the following steps. ``` [ { "metadata": { "id": "f99e055f-b35d-208b-63b1-f4222b80151a", "name": "realtheory-cluster-01", "timestamp": "2024-07-17T20:15:15.333644Z" }, "object": { ... }, ... } ] ``` ### Step 2: Get the namespaces for the cluster Using the `<cluster-id>` from Step 1, call the method below to get all namespaces associated with the cluster. ``` GET /theory/api/v1/k8s/namespaces/search/query/{query}?index={index}&count={count}&order={order}&direction={direction} ``` where - `{query}` - is a [query](/v1/docs/queries) used to limit the results to namespaces within the given cluster. - `{index}` - is the starting index of the namespaces to include in the list. This parameter is optional and defaults to 0 if not specified. - `{count}` - is the maximum number of namespaces to return, up to a limit of 500. This parameter is optional and defaults to 100 if not specified. - `{order}` - is a string containing the name of the attribute to sort on. This parameter is optional. - `{direction}` - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified. **Note:** To retrieve all namespaces, increment the `{index}` by the `{count}` on each subsequent call until a response returns fewer namespaces than the `{count}` requested. See [Paging](/v1/docs/paging) for more details on how to page through all results. #### Example ``` GET theory/api/v1/k8s/namespaces/search/query/metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a?index=0&count=100&order=metadata.name&direction=0 ``` which returns a list of the first 100 [Namespace](/v1/docs/k8s-namespace) objects for the cluster, sorted by name in ascending order. Each object's `metadata.id` is the `<namespace-id>` and its `metadata.name` is the `<namespace-name>` used in the next step. ``` [ { "metadata": { "id": "568490d7-9f0e-41ad-b416-8392056cb455", "name": "web-app", "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a", "clusterName": "realtheory-cluster-01", "timestamp": "2024-07-17T20:15:15.333644Z" }, "object": { ... }, ... } ] ``` ### Step 3: Get the pods Using the `<cluster-id>` from Step 1 and a `<namespace-id>` from Step 2, call the method below to get the pods for that cluster and namespace. ``` GET /theory/api/v1/k8s/pods/search/query/{query}?index={index}&count={count}&order={order}&direction={direction} ``` where - `{query}` - is a [query](/v1/docs/queries) used to limit the results to pods within a given namespace and cluster. - `{index}` - is the starting index of the pods to include in the list. This parameter is optional and defaults to 0 if not specified. - `{count}` - is the maximum number of pods to return, up to a limit of 500. This parameter is optional and defaults to 100 if not specified. - `{order}` - is a string containing the name of the attribute to sort on. This parameter is optional. - `{direction}` - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified. **Note:** To retrieve all pods, increment the `{index}` by the `{count}` on each subsequent call until a response returns fewer pods than the `{count}` requested. See [Paging](/v1/docs/paging) for more details on how to page through all results. #### Example ``` GET theory/api/v1/k8s/pods/search/query/metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a AND metadata.namespaceId=568490d7-9f0e-41ad-b416-8392056cb455?index=0&count=100&order=metadata.name&direction=0 ``` which returns a list of the first 100 pods associated with the given namespace and cluster, sorted by name in ascending order. **Notes:** - A pod provides the concrete details, including the raw Kubernetes resource, related to a Kubernetes Pod. - As cluster and namespace names are not guaranteed to be unique across all environments, it is strongly recommended to use the `metadata.clusterId` and `metadata.namespaceId` fields, as shown above. See [Objects](/v1/docs/objects) for more details on querying related objects. #### Output Returns an array of [Pod](/v1/docs/k8s-pod) objects: ``` [ { "metadata": { "id": "a6095791-7552-474a-8865-85bfa2efd4b9", "name": "activity-6c467dfcd-jn2qg", "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a", "clusterName": "realtheory-cluster-01", "nodeId": "1206f66c-65a1-4ae6-a7cc-e5ced6cc2ae4", "nodeName": "aks-userpool-15373879-vmss000029", "namespaceId": "568490d7-9f0e-41ad-b416-8392056cb455", "namespaceName": "web-app", "deploymentId": "1284d4ef-558a-4d57-8a2e-21e218f9a9f3", "deploymentName": "activity", "timestamp": "2024-07-17T20:15:15.333644Z" }, "object": { "metadata": { "name": "activity-6c467dfcd-jn2qg", "namespace": "web-app", "uid": "a6095791-7552-474a-8865-85bfa2efd4b9", ... }, "spec": { "nodeName": "aks-userpool-15373879-vmss000029", ... }, "status": { "phase": "Running", "podIP": "10.244.1.23", ... } }, ... }, { "metadata": { "id": "e3b2c9f4-1a77-42d1-9f0e-7c1d2a9b04e5", "name": "queue-767b8d9c88-rwvjx", "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a", "clusterName": "realtheory-cluster-01", "nodeId": "1206f66c-65a1-4ae6-a7cc-e5ced6cc2ae4", "nodeName": "aks-userpool-15373879-vmss000029", "namespaceId": "568490d7-9f0e-41ad-b416-8392056cb455", "namespaceName": "web-app", "deploymentId": "a6ffe9d7-8bda-43a9-bc65-4f7dfdbc7ebf", "deploymentName": "queue", "timestamp": "2024-07-17T20:15:15.333644Z" }, "object": { ... }, ... }, ... ] ``` **Note:** Content has been omitted from the JSON response above for brevity.