---
title: K8s Cluster
description: Interact with a Kubernetes cluster to retrieve GPU billing usage.
canonical: 'https://lightning.ai/docs/sdk/stable/api/k8s-cluster'
---
# K8s Cluster {#k8s-cluster}

### `class lightning_sdk.k8s_cluster.K8sCluster(cloud_account)` {#lightning_sdk.k8s_cluster.K8sCluster}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

Interact with a Kubernetes cluster to retrieve GPU billing usage.

Connect to a Kubernetes cluster by cloud account.

Parameters:

*   **cloud\_account** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – The cloud account ID associated with the cluster.
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    

#### `get_billing_usage(start_date=None, end_date=None, print_data=False)` {#lightning_sdk.k8s_cluster.K8sCluster.get_billing_usage}

Retrieve GPU billing usage for this cluster.

Parameters:

*   **start\_date** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)")\]) – UTC start of the query window. Defaults to None (no lower bound).
    
*   **end\_date** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)")\]) – UTC end of the query window. Defaults to None (no upper bound).
    
*   **print\_data** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – Whether to print the raw usage data to stdout. Defaults to False.
    
*   **start\_date** ([_datetime_](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") _|_ _None_)
    
*   **end\_date** ([_datetime_](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") _|_ _None_)
    
*   **print\_data** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    

Returns:

Hourly GPU usage breakdown and the total billed GPU count.

Return type:

[K8sUsageResponse](#lightning_sdk.k8s_cluster.K8sUsageResponse "lightning_sdk.k8s_cluster.K8sUsageResponse")

### `class lightning_sdk.k8s_cluster.K8sUsageResponse(hours, total_usage)` {#lightning_sdk.k8s_cluster.K8sUsageResponse}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

Aggregated GPU billing response for a queried time range.

Parameters:

*   **hours** ([_List_](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")_\[_[_HourlyUsage_](#lightning_sdk.k8s_cluster.HourlyUsage "lightning_sdk.k8s_cluster.HourlyUsage")_\]_)
    
*   **total\_usage** ([_float_](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)"))
    

#### `hours` {#lightning_sdk.k8s_cluster.K8sUsageResponse.hours}

Per-hour breakdown of GPU usage.

#### `total_usage` {#lightning_sdk.k8s_cluster.K8sUsageResponse.total_usage}

Sum of billed GPUs across all hours.

### `class lightning_sdk.k8s_cluster.HourlyUsage(time, available_gpus, billed_gpus)` {#lightning_sdk.k8s_cluster.HourlyUsage}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

GPU billing data for a single one-hour window.

Parameters:

*   **time** ([_datetime_](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)"))
    
*   **available\_gpus** ([_int_](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))
    
*   **billed\_gpus** ([_int_](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))
    

#### `time` {#lightning_sdk.k8s_cluster.HourlyUsage.time}

Start of the hour (UTC).

#### `available_gpus` {#lightning_sdk.k8s_cluster.HourlyUsage.available_gpus}

Total GPUs allocated during this hour.

#### `billed_gpus` {#lightning_sdk.k8s_cluster.HourlyUsage.billed_gpus}

GPUs that were actively billed during this hour.

---

**Navigation**

- Parent: [API Reference](/docs/sdk/2026.11.04/api.md)