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:

NameTypeRequiredDefaultDescription
applicationstringNodefaultArgoCD application name. Falls back to the config entry with "default": true.
groupKindstringNodeploymentKubernetes 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:

NameTypeRequiredDefaultDescription
applicationstringNodefaultArgoCD application name
groupKindstringNodeploymentResource kind
rowstringYesRow identifier from dashboard config
graphstringYesGraph identifier from dashboard config
namespacestringYesKubernetes namespace
namestringYesResource name (workloads: name-.* pattern, pods: exact name)
podsstringNoComma-separated pod names; overrides name as the pod filter
durationstringNo1hTime 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:

NameTypeRequiredDefaultDescription
namespacestringYesKubernetes namespace
namestringYesResource name
kindstringNoDeploymentResource kind: Deployment, StatefulSet, Pod
rangestringNo(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:

NameTypeRequiredDefaultDescription
namespacestringYesKubernetes namespace
rangestringNo(instant only)Time range: 1h, 6h, 24h, 7d
podsstringNoComma-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:

NameTypeRequiredDefaultDescription
namespacestringYesKubernetes namespace
namestringNoResource name (required if pods not set)
kindstringNoDeploymentResource kind
podsstringNoComma-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:

NameTypeRequiredDefaultDescription
namespacestringYesKubernetes namespace
namestringNoResource name
kindstringNoDeploymentResource kind
rangestringNo1hTime range
podsstringNoComma-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.