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

# Querying Kubernetes metrics

Read Kubernetes node and pod metrics with the [Public API
(V2)](/api/v2/overview). All endpoints authenticate with your personal API token,
are scoped to a single `site_id`, and take a `from`/`to` time range.

## Query node metrics

Returns one `NodesRow` per node snapshot in the time range.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/kubernetes/nodes
  ```
</CodeGroup>

### Request body

| Field       | Type              | Required | Description                                               |
| ----------- | ----------------- | -------- | --------------------------------------------------------- |
| `site_id`   | string            | Yes      | Site to query.                                            |
| `from`      | string (ISO 8601) | Yes      | Time range start (inclusive).                             |
| `to`        | string (ISO 8601) | Yes      | Time range end (inclusive).                               |
| `node_name` | string            | No       | Filter to a single node. An empty string means no filter. |

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_id": "YOUR-SITE-ID",
    "from": "2026-06-22T00:00:00Z",
    "to": "2026-06-22T01:00:00Z",
    "node_name": ""
  }
  ```
</CodeGroup>

### Response

Returns an array of `NodesRow` objects, one per node snapshot. Each has these
fields:

| Field                      | Type              | Description                              |
| -------------------------- | ----------------- | ---------------------------------------- |
| `timestamp`                | string (ISO 8601) | When the snapshot was taken.             |
| `node_name`                | string            | Kubernetes node name.                    |
| `cpu_usage_nano_cores`     | number            | CPU usage in nanocores.                  |
| `memory_rss_bytes`         | number            | Resident set size (RSS) memory in bytes. |
| `memory_usage_bytes`       | number            | Total memory usage in bytes.             |
| `memory_working_set_bytes` | number            | Working set memory in bytes.             |
| `memory_page_faults`       | number            | Page fault count.                        |
| `memory_major_page_faults` | number            | Major page fault count.                  |
| `fs_used_bytes`            | number            | Filesystem space used in bytes.          |
| `fs_available_bytes`       | number            | Filesystem space available in bytes.     |
| `fs_capacity_bytes`        | number            | Total filesystem capacity in bytes.      |
| `fs_inodes_free`           | number            | Free filesystem inode count.             |
| `fs_inodes_used`           | number            | Used filesystem inode count.             |
| `fs_inodes`                | number            | Total filesystem inode count.            |
| `network_rx_bytes`         | number            | Network bytes received.                  |
| `network_tx_bytes`         | number            | Network bytes transmitted.               |
| `phase`                    | number            | Node phase, as a numeric value.          |

## Query pod metrics

Returns one `PodsRow` per pod snapshot in the time range.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/kubernetes/pods
  ```
</CodeGroup>

### Request body

| Field        | Type                 | Required | Description                                                |
| ------------ | -------------------- | -------- | ---------------------------------------------------------- |
| `site_id`    | string               | Yes      | Site to query.                                             |
| `from`       | string (ISO 8601)    | Yes      | Time range start (inclusive).                              |
| `to`         | string (ISO 8601)    | Yes      | Time range end (inclusive).                                |
| `namespaces` | string\[]            | No       | Filter to these namespaces. Empty means all namespaces.    |
| `pod_name`   | string               | No       | Filter to a single pod. An empty string means no filter.   |
| `node_names` | string\[]            | No       | Filter to these nodes. Empty means all nodes.              |
| `state`      | `PodState` or `null` | No       | Filter to a single pod state. See [pod state](#pod-state). |

### Response

Returns an array of `PodsRow` objects, one per pod snapshot. Each has these
fields:

| Field                              | Type              | Description                                                  |
| ---------------------------------- | ----------------- | ------------------------------------------------------------ |
| `timestamp`                        | string (ISO 8601) | When the snapshot was taken.                                 |
| `pod_name`                         | string            | Pod name.                                                    |
| `pod_namespace`                    | string            | Kubernetes namespace the pod belongs to.                     |
| `node_name`                        | string            | Node name this pod runs on.                                  |
| `cpu_usage_nano_cores`             | number            | CPU usage in nanocores.                                      |
| `cpu_usage_core_nano_seconds`      | number            | Cumulative CPU usage in core-nanoseconds.                    |
| `memory_rss_bytes`                 | number            | Resident set size (RSS) memory in bytes.                     |
| `memory_usage_bytes`               | number            | Total memory usage in bytes.                                 |
| `memory_working_set_bytes`         | number            | Working set memory in bytes.                                 |
| `memory_page_faults`               | number            | Page fault count.                                            |
| `memory_major_page_faults`         | number            | Major page fault count.                                      |
| `ephemeral_storage_used_bytes`     | number            | Ephemeral storage used in bytes.                             |
| `ephemeral_storage_capacity_bytes` | number            | Ephemeral storage capacity in bytes.                         |
| `network_rx_bytes`                 | number            | Network bytes received.                                      |
| `network_tx_bytes`                 | number            | Network bytes transmitted.                                   |
| `process_count`                    | number            | Running process count.                                       |
| `phase`                            | `PodPhase`        | Current lifecycle phase. See [pod phase](#pod-phase).        |
| `state`                            | `PodState`        | Derived pod state. See [pod state](#pod-state).              |
| `containers`                       | `Container[]`     | Containers running in this pod. See [container](#container). |
| `pod_restart_count`                | number            | Total container restarts for this pod.                       |
| `pod_uptime_seconds`               | number            | Pod uptime in seconds.                                       |

## Query pod overview

Returns pod metadata and status rather than raw metrics, as one
`PodOverviewRow` per pod.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/kubernetes/pods/overview
  ```
</CodeGroup>

### Request body

| Field        | Type              | Required | Description                                             |
| ------------ | ----------------- | -------- | ------------------------------------------------------- |
| `site_id`    | string            | Yes      | Site to query.                                          |
| `from`       | string (ISO 8601) | Yes      | Time range start (inclusive).                           |
| `to`         | string (ISO 8601) | Yes      | Time range end (inclusive).                             |
| `namespaces` | string\[]         | No       | Filter to these namespaces. Empty means all namespaces. |
| `query`      | string            | No       | Free-text search query for filtering pods.              |

### Response

Returns an array of `PodOverviewRow` objects, one per pod. Each has these fields, which are all **required**:

| Field                | Type               | Description                                                             |
| -------------------- | ------------------ | ----------------------------------------------------------------------- |
| `timestamp`          | string (ISO 8601)  | When the snapshot was taken.                                            |
| `node_name`          | string             | Node name this pod runs on.                                             |
| `pod_name`           | string             | Pod name.                                                               |
| `pod_namespace`      | string             | Kubernetes namespace the pod belongs to.                                |
| `pod_uuid`           | string             | Unique pod identifier.                                                  |
| `phase`              | `PodPhase`         | Current lifecycle phase. See [pod phase](#pod-phase).                   |
| `labels`             | object             | Kubernetes labels attached to the pod.                                  |
| `owner_references`   | `OwnerReference[]` | Owner references for this pod. See [owner reference](#owner-reference). |
| `containers`         | `Container[]`      | Containers running in this pod. See [container](#container).            |
| `state`              | `PodState`         | Derived pod state. See [pod state](#pod-state).                         |
| `pod_restart_count`  | number             | Total container restarts for this pod.                                  |
| `pod_uptime_seconds` | number             | Pod uptime in seconds.                                                  |

## Reference

### Pod phase

`phase` is the Kubernetes lifecycle phase: `Running`, `Succeeded`, `Pending`,
`Failed`, or `Unknown`.

### Pod state

`state` is a derived state combining phase and container statuses: `Running`,
`Succeeded`, `Pending`, `Failed`, or `Unknown`.

### Container

Each entry in `containers` has a `name`, a `status` (`Running`, `Terminated`,
`Waiting`, or `Unknown`), an `exit_code` (`0` means success), and a human-readable
`reason`.

### Owner reference

Each entry in `owner_references` has the owning resource's `name`, `kind` (such as
`ReplicaSet` or `DaemonSet`), and `namespace`.