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).

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:

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:

All query parameters are available as Go text/template variables in PromQL expressions (e.g., {{.namespace}}, {{.name}}, {{.duration}}).

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 query builder.

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:

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": "" }
]

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:

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:

Response:

[
  {
    "pod": "guestbook-ui-abc123",
    "cpu": "12.5 m",
    "memory": "45.2 MiB",
    "netRx": "1.2 KB/s",
    "netTx": "0.8 KB/s",
    "restarts": "0"
  }
]

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:

Response:

[
  {
    "metric": "CPU Usage",
    "unit": "millicores",
    "timestamps": ["2025-03-16T10:00:00Z", "..."],
    "pods": [
      {
        "pod": "guestbook-ui-abc123",
        "values": [12.5, null, 13.0]
      }
    ]
  }
]

Custom query

GET /api/v1/query?query={promql}&range={range}

Executes an arbitrary PromQL query. Used by the interactive Query Builder.

Parameters:

Queries containing delete or drop are rejected (403).

Instant response:

{
  "samples": [
    { "labels": { "pod": "guestbook-ui-abc123" }, "value": 12.5 }
  ]
}

Range response:

{
  "multiSeries": [
    {
      "label": "pod=guestbook-ui-abc123",
      "series": [{ "time": "...", "value": 12.5 }]
    }
  ]
}

Discover metrics

GET /api/v1/discover?namespace={ns}&search={term}

Lists available Prometheus metric names, categorized and with auto-generated PromQL templates.

Parameters:

Response (max 100 results):

[
  {
    "name": "container_cpu_usage_seconds_total",
    "category": "cpu",
    "query": "sum(rate(container_cpu_usage_seconds_total{namespace="default"}[5m]))"
  }
]

Categories: cpu, memory, network, disk, pod, node, deployment, statefulset, namespace, other.

Label discovery

GET /api/v1/labels?metric={name}&label={label}&namespace={ns}

Returns label names or values for a Prometheus metric.

Parameters:

Label names response (no label param):

["pod", "container", "namespace", "node"]

Label values response (with label param):

["guestbook-ui-abc123", "guestbook-ui-def456"]

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 for disallowed queries, 404 for config lookups that fail, 500 for internal errors.