--- title: "How To: List the Namespace Summaries for a Kubernetes Cluster" slug: "how-to-list-the-namespaces-for-a-kubernetes-cluster" updated: 2026-07-09T11:47:57Z published: 2026-07-09T11:47:57Z canonical: "resources.realtheory.io/how-to-list-the-namespaces-for-a-kubernetes-cluster" --- > ## 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 Namespace Summaries for a Kubernetes Cluster 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 namespace summaries for a given cluster is a two-step process, where the first step resolves the identifier needed by the second. Both calls are made against the [K8sSummary](https://api-dev.realtheory.io/swagger/k8ssummary/index.html) endpoint. 1. **Look up the cluster summary by name** using the `ClusterSummaries` endpoint with the query `metadata.name=<cluster-name>`. This gives the `<cluster-id>`. Example query: `metadata.name=realtheory-cluster-01` 2. **Get all namespace summaries associated with the cluster** using the `NamespaceSummaries` endpoint with the query `metadata.clusterId=<cluster-id>`. Example query: `metadata.clusterId=f99e055f-b35d-208b-63b1-f4222b80151a` **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 summary by name Call the method below to find the cluster summary whose name matches the given cluster name. ``` GET /theory/api/v1/k8ssummary/clustersummaries/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 cluster summaries to include in the list. This parameter is optional and defaults to 0 if not specified. - `{count}` - is the maximum number of cluster summaries 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/k8ssummary/clustersummaries/search/query/metadata.name=realtheory-cluster-01?index=0&count=100&order=metadata.name&direction=0 ``` which returns the [ClusterSummary](/v1/docs/k8ssummary-cluster-summary) objects whose name is `realtheory-cluster-01`. The `metadata.id` field of the returned object is the `<cluster-id>` used in the following step. ``` [ { "metadata": { "id": "f99e055f-b35d-208b-63b1-f4222b80151a", "name": "realtheory-cluster-01", "timestamp": "2024-03-06T20:17:25.0471704Z" }, ... } ] ``` ### Step 2: Get the namespace summaries for the cluster Using the `<cluster-id>` from Step 1, call the method below to get all namespace summaries associated with the cluster. ``` GET /theory/api/v1/k8ssummary/namespacesummaries/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 for a given cluster. - `{index}` - is the starting index of the namespace summaries to include in the list. This parameter is optional and defaults to 0 if not specified. - `{count}` - is the maximum number of namespace summaries 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 namespace summaries, increment the `{index}` by the `{count}` on each subsequent call until a response returns fewer namespace summaries than the `{count}` requested. See [Paging](/v1/docs/paging) for more details on how to page through all results. #### Example ``` GET theory/api/v1/k8ssummary/namespacesummaries/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 summaries associated with the given cluster, sorted by name in ascending order. **Notes:** - A namespace summary is an object that summarizes key information related to a Kubernetes namespace. - As cluster names are not guaranteed to be unique across all environments, it is strongly recommended to use the `metadata.clusterId` field, as shown above. See [Objects](/v1/docs/objects) for more details on querying related objects. #### Output Returns an array of [NamespaceSummary](/v1/docs/k8ssummary-namespacesummary) objects: ``` [ { "metadata": { "id": "3fa272eb-7faa-41f2-a416-2c59b950b277", "name": "cert-manager", "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a", "clusterName": "realtheory-cluster-01", "owners": null, "timestamp": "2024-03-06T20:17:25.0471704Z" }, ... }, { "metadata": { "id": "b1cb1122-68e6-41f8-bd62-8b6e2ba675cd", "name": "default", "clusterId": "f99e055f-b35d-208b-63b1-f4222b80151a", "clusterName": "realtheory-cluster-01", "owners": null, "timestamp": "2024-03-06T20:16:24.2065431Z" }, ... }, ... ] ``` **Note:** Content has been omitted from the JSON response above for brevity.