> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List kubernetes clusters

> Returns kubernetes cluster metadata for the tenant selected by the X-CostGraph-Tenant-ID header



## OpenAPI

````yaml /api-reference/costgraph/openapi.json get /api/v1/tenant/clusters
openapi: 3.0.0
info:
  description: Read and manage your CostGraph organization, spend, alerts, and settings.
  title: CostGraph API
  contact: {}
  version: '1.0'
servers:
  - url: https://api.costgraph.ai
security: []
tags:
  - name: ai
    x-group: AI
  - name: ai-serving
    x-group: AI serving
  - name: anomalies
    x-group: Anomalies
  - name: auth
    x-group: Auth
  - name: billing
    x-group: Billing
  - name: billing-export
    x-group: Billing export
  - name: budgets
    x-group: Budgets
  - name: ci
    x-group: CI
  - name: compute-recommendations
    x-group: Compute recommendations
  - name: config
    x-group: Config
  - name: cost
    x-group: Cost
  - name: gpus
    x-group: GPUs
  - name: graphai
    x-group: Graph AI
  - name: infracost
    x-group: Infracost
  - name: integrations
    x-group: Integrations
  - name: invitations
    x-group: Invitations
  - name: kubernetes-clusters
    x-group: Kubernetes clusters
  - name: marketplace
    x-group: Marketplace
  - name: network-requests
    x-group: Network requests
  - name: notifications
    x-group: Notifications
  - name: oauth
    x-group: OAuth
  - name: oauth-clients
    x-group: OAuth clients
  - name: opencost
    x-group: OpenCost
  - name: organization
    x-group: Audit log
  - name: organizations
    x-group: Organizations
  - name: placement-alternatives
    x-group: Placement alternatives
  - name: reports
    x-group: Reports
  - name: service-map
    x-group: Service map
  - name: settings
    x-group: Settings
  - name: sso
    x-group: Single sign-on
  - name: tenants
    x-group: Tenants
  - name: user
    x-group: Users
  - name: virtual-machines
    x-group: Virtual machines
  - name: virtual-tags
    x-group: Virtual tags
  - name: workflows
    x-group: Workflows
paths:
  /api/v1/tenant/clusters:
    get:
      tags:
        - kubernetes-clusters
      summary: List kubernetes clusters
      description: >-
        Returns kubernetes cluster metadata for the tenant selected by the
        X-CostGraph-Tenant-ID header
      parameters:
        - description: Tenant ID
          name: X-CostGraph-Tenant-ID
          in: header
          required: true
          schema:
            type: string
        - description: Filter by cloud provider (repeat param or comma-separated)
          name: providers
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - description: Filter by cluster status (repeat param or comma-separated)
          name: status
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - description: Filter by operator version (repeat param or comma-separated)
          name: operator_versions
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - description: Filter by Kubernetes version (repeat param or comma-separated)
          name: kubernetes_versions
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - description: Filter by region (repeat param or comma-separated)
          name: regions
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - description: Search by cluster name
          name: search
          in: query
          schema:
            type: string
        - description: >-
            Sort field (name, -name, provider, -provider, node_count,
            -node_count, current_period_cost, -current_period_cost,
            previous_period_cost, -previous_period_cost, cost_change_percent,
            -cost_change_percent, possible_savings, -possible_savings)
          name: sort
          in: query
          schema:
            type: string
        - description: Number of rows to return (default 50, max 200)
          name: limit
          in: query
          schema:
            type: integer
        - description: Rows to skip before returning results (default 0)
          name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/responses.SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/k8scluster.ListResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses.ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    responses.SuccessResponse:
      type: object
      required:
        - message
        - status
      properties:
        data: {}
        message:
          type: string
          example: some message
        status:
          type: string
          example: success
    k8scluster.ListResult:
      type: object
      required:
        - items
        - limit
        - offset
        - total_count
      properties:
        items:
          description: Clusters on the current page, ordered by the request's sort filter.
          type: array
          items:
            $ref: '#/components/schemas/k8scluster.Info'
        limit:
          description: Page size that produced Items, matching the request's limit filter.
          type: integer
        offset:
          description: >-
            Number of clusters skipped before Items, matching the request's
            offset

            filter.
          type: integer
        total_count:
          description: |-
            Total number of clusters matching the request's filters, across all
            pages.
          type: integer
    responses.ErrorResponse:
      type: object
      required:
        - message
        - status
      properties:
        message:
          type: string
          example: some message
        status:
          type: string
          example: error
    k8scluster.Info:
      type: object
      required:
        - cost_info
        - current_spend
        - id
        - name
        - node_count
        - provider
        - region
        - status
      properties:
        cost_info:
          description: |-
            Full cost breakdown for the cluster over the selected and previous
            periods.
          allOf:
            - $ref: '#/components/schemas/k8scluster.CostInfo'
          x-nullable: 'false'
        current_spend:
          description: |-
            Spend in the selected period, in CostInfo.Currency. Equal to
            CostInfo.CurrentPeriodCost.
          type: number
          x-semantic: costAmount
        id:
          description: Unique identifier of the cluster.
          type: string
          x-semantic: resourceId
        name:
          description: Display name of the cluster.
          type: string
        node_count:
          description: Number of nodes currently in the cluster.
          type: integer
        possible_savings:
          description: >-
            Monthly savings available by applying rightsizing recommendations

            across the cluster, in CostInfo.Currency. Always present; zero when
            no

            recommendation exists for this cluster.
          type: number
          x-semantic: costAmount
          nullable: true
        provider:
          description: Cloud provider the cluster runs on.
          type: string
        recommended_spend:
          description: |-
            Monthly spend after applying rightsizing recommendations, in
            CostInfo.Currency. Always present; equal to CurrentSpend when no
            recommendation exists for this cluster.
          type: number
          x-semantic: costAmount
          nullable: true
        region:
          description: Region the cluster runs in.
          type: string
        status:
          description: >-
            Health status of the cluster: healthy when the agent reported
            recently,

            disconnected when it has not, degraded when it has never reported.
          type: string
    k8scluster.CostInfo:
      type: object
      required:
        - cost_data_available
        - currency
        - current_period_cost
        - observed_hours
        - period
        - period_end
        - period_start
        - previous_period_end
        - previous_period_start
      properties:
        cost_change_amount:
          description: >-
            Signed absolute change of CurrentPeriodCost against
            PreviousPeriodCost,

            in Currency. Null under the same condition as PreviousPeriodCost.
          type: number
          x-semantic: costAmount
          nullable: true
        cost_change_percent:
          description: >-
            Signed percent change of CurrentPeriodCost against
            PreviousPeriodCost.

            Null under the same condition as PreviousPeriodCost.
          type: number
          x-semantic: percentage
          nullable: true
        cost_data_available:
          description: >-
            False when no cost data exists for the cluster in the selected
            period,

            in which case the cost fields above are zero rather than meaningful.
          type: boolean
        currency:
          description: Billing currency the cost figures are expressed in.
          type: string
          x-semantic: currencyCode
        current_period_cost:
          description: Spend in the selected period, in Currency.
          type: number
          x-semantic: costAmount
        observed_hours:
          description: >-
            Hours of usage data actually observed within the selected period,
            for

            judging how complete CurrentPeriodCost is.
          type: number
        period:
          description: |-
            Named period the cost figures cover, e.g. "month_to_date" or
            "last_30d", matching the request's period filter.
          type: string
        period_end:
          description: End of the selected period, exclusive.
          type: string
        period_start:
          description: Start of the selected period, inclusive.
          type: string
        previous_period_cost:
          description: |-
            Spend in the previous period, in Currency. Null when the previous
            period has no comparable cost data.
          type: number
          x-semantic: costAmount
          nullable: true
        previous_period_end:
          description: End of the comparable previous period, exclusive.
          type: string
        previous_period_start:
          description: Start of the comparable previous period, inclusive.
          type: string
  securitySchemes:
    BearerAuth:
      description: Enter "Bearer {token}"
      type: apiKey
      name: Authorization
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.