Metrics API
The metrics backend exposes a JSON HTTP API consumed by the UI extension via ArgoCD’s proxy at /extensions/metrics/.
All requests receive ArgoCD identity headers (Argocd-Username, Argocd-User-Id, Argocd-User-Groups, Argocd-Target-Cluster-URL).
Authorization
Every data endpoint requires the Argocd-Application-Name header (namespace:name format, set automatically by ArgoCD’s proxy). The backend returns 403 if the header is missing or if the requested namespace is not managed by that Application (its destination namespace plus namespaces in status.resources). The backend needs get on applications.argoproj.io for this lookup; the Helm chart grants it by default.
Config-driven dashboard endpoints
These are the primary endpoints used by the config-driven dashboard system.
Get dashboard config
GET /api/v1/dashboards?application={name}&groupKind={kind} Returns the dashboard layout (tabs, rows, graphs metadata) for the UI to render.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
application | string | No | default | ArgoCD application name. Falls back to the config entry with "default": true. |
groupKind | string | No | deployment | Kubernetes resource kind: deployment, statefulset, pod |
Response:
{
"groupKind": "deployment",
"tabs": ["Resource Usage", "Container Breakdown"],
"intervals": ["1h", "6h", "24h", "7d"],
"rows": [
{
"name": "cpu-memory",
"title": "CPU & Memory",
"tab": "Resource Usage",
"graphs": [
{
"name": "cpu-by-pod",
"title": "CPU Usage by Pod",
"graphType": "line",
"metricName": "pod",
"queryExpression": "sum by (pod) (rate(...))",
"yAxisUnit": "millicores"
}
]
}
]
} Get graph data
GET /api/v1/graph?application={name}&groupKind={kind}&row={row}&graph={graph}&namespace={ns}&name={name}&duration={dur} Executes a PromQL template for a specific graph and returns time series data.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
application | string | No | default | ArgoCD application name |
groupKind | string | No | deployment | Resource kind |
row | string | Yes | Row identifier from dashboard config | |
graph | string | Yes | Graph identifier from dashboard config | |
namespace | string | Yes | Kubernetes namespace | |
name | string | Yes | Resource name (workloads: name-.* pattern, pods: exact name) | |
pods | string | No | Comma-separated pod names; overrides name as the pod filter | |
duration | string | No | 1h | Time range: 1h, 6h, 24h, 7d |
PromQL templates support the variables {{.namespace}}, {{.name}}, {{.podFilter}} (built from pods or name), {{.cluster}} and {{.clusterMatcher}} (set when CLUSTER_LABEL is configured). Values are escaped before substitution to prevent PromQL injection.
Response:
{
"series": [
{
"label": "guestbook-ui-abc123",
"values": [
{ "time": "2025-03-16T10:00:00Z", "value": 12.5 },
{ "time": "2025-03-16T10:00:30Z", "value": null }
]
}
]
} Values are converted based on yAxisUnit: bytes to MiB, bytes/s to KB/s, millicores and count passed through. null values indicate gaps in the data.
Legacy endpoints
These endpoints are still used by the summary cards, pod breakdown table, and per-pod charts.
Resource metrics
GET /api/v1/resource-metrics?namespace={ns}&name={name}&kind={kind}&range={range} Returns instant summary or time series metrics for a specific workload or pod.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
namespace | string | Yes | Kubernetes namespace | |
name | string | Yes | Resource name | |
kind | string | No | Deployment | Resource kind: Deployment, StatefulSet, Pod |
range | string | No | (instant) | Time range for series data: 1h, 6h, 24h, 7d |
Instant response (no range):
[
{ "name": "CPU", "value": "12.5", "unit": "millicores" },
{ "name": "Memory", "value": "45.2", "unit": "MiB" },
{ "name": "Network RX", "value": "1.2", "unit": "KB/s" },
{ "name": "Network TX", "value": "0.8", "unit": "KB/s" },
{ "name": "Restarts", "value": "0", "unit": "" }
] value is always expressed in unit: CPU in millicores, memory in MiB, network in KB/s. The backend does not switch to cores or GiB for large values.
Range response (with range):
[
{
"name": "CPU",
"unit": "millicores",
"series": [
{ "time": "2025-03-16T10:00:00Z", "value": 12.5 }
]
}
] App metrics
GET /api/v1/app-metrics?namespace={ns}&range={range} Returns namespace-wide aggregate metrics (all pods in a namespace).
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
namespace | string | Yes | Kubernetes namespace | |
range | string | No | (instant only) | Time range: 1h, 6h, 24h, 7d |
pods | string | No | Comma-separated pod names to scope the aggregation |
Response:
{
"summary": [
{ "name": "CPU", "value": "45.2", "unit": "millicores" },
{ "name": "Memory", "value": "128.5", "unit": "MiB" }
],
"timeSeries": [
{
"name": "CPU",
"unit": "millicores",
"series": [{ "time": "...", "value": 45.2 }]
}
]
} Pod breakdown
GET /api/v1/pod-breakdown?namespace={ns}&name={name}&kind={kind}&pods={pods} Returns per-pod instant metrics for the pod details table.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
namespace | string | Yes | Kubernetes namespace | |
name | string | No | Resource name (required if pods not set) | |
kind | string | No | Deployment | Resource kind |
pods | string | No | Comma-separated pod names (alternative to name) |
Response:
[
{
"pod": "guestbook-ui-abc123",
"cpu": "12.5",
"cpuRequest": "100.0",
"cpuLimit": "1500.0",
"memory": "45.2",
"memoryRequest": "64.0",
"memoryLimit": "1024.0",
"netRx": "1.2",
"netTx": "0.8",
"restarts": "0"
}
] Values are strings in fixed units: CPU in millicores, memory in MiB, network in KB/s. A missing request or limit is "-". The UI scales them for display (1500.0 millicores shows as 1.50 cores).
Per-pod time series
GET /api/v1/per-pod-series?namespace={ns}&name={name}&kind={kind}&range={range}&pods={pods} Returns per-pod time series for multi-line charts (CPU, Memory, Network RX, Network TX).
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
namespace | string | Yes | Kubernetes namespace | |
name | string | No | Resource name | |
kind | string | No | Deployment | Resource kind |
range | string | No | 1h | Time range |
pods | string | No | Comma-separated pod names |
Response:
[
{
"metric": "CPU Usage",
"unit": "millicores",
"timestamps": ["2025-03-16T10:00:00Z", "..."],
"pods": [
{
"pod": "guestbook-ui-abc123",
"values": [12.5, null, 13.0]
}
]
}
] Health check
GET /healthz Returns 200 OK. No body.
Error responses
All endpoints return errors as JSON:
{ "error": "description of what went wrong" } HTTP status codes: 400 for missing parameters, 403 when namespace authorization fails, 404 for config lookups that fail, 500 for internal errors, 502 when a Prometheus query fails. A 502 covers the whole response: one failed query fails the request rather than returning partial data. The exception is a graph’s threshold lines, which are left out if their query fails.