Metrics query API

Metrics query API

Query measurements with explicit sources, resolution, and missing-data behavior.

Metrics queries read infrastructure observations without changing resource state. The API returns units and sample timestamps so consumers can distinguish missing data from a measured zero.

POST/organizations/{organization_id}/metrics/query
Scope
metrics:read
Auth
Bearer API key

Returns infrastructure measurements for the selected time range and resources.

Send a metric name, time range, resolution, and resource selection. Selection is constrained by the caller's role bindings even when an organization path is used.

To request a bounded CPU-utilization query, send:

JSON
{
  "metric": "droplet.cpu.utilization",
  "resource_ids": ["drp_web01", "drp_web02"],
  "start": "2026-01-29T11:00:00Z",
  "end": "2026-01-29T12:00:00Z",
  "step_seconds": 60,
  "aggregation": "mean"
}

step_seconds is a positive integer. Supported resolution depends on retained source data; a request below the available resolution returns 422 resolution_unavailable with supported values. The interval includes start and excludes end. End must be later than start.

Aggregations are mean, min, max, or a metric-supported percentile. An incompatible aggregation returns 422 invalid_aggregation rather than converting a counter into an undocumented rate.

Response

The response identifies the series, source, resolution, and samples:

JSON
{
  "data": {
    "metric": "droplet.cpu.utilization",
    "unit": "ratio",
    "step_seconds": 60,
    "series": [
      {
        "resource_id": "drp_web01",
        "source": "hypervisor",
        "points": [
          ["2026-01-29T11:00:00Z", 0.42],
          ["2026-01-29T11:01:00Z", null]
        ]
      }
    ]
  }
}

null means no usable sample for that bucket. It is not a zero or a healthy result. CPU ratio uses 1.0 for the selected resource's configured allocation; clients should not compare it with a raw host-core count without conversion.

Resource filtering

Use either explicit IDs or a project-scoped label selector. Forbidden IDs reject the explicit query rather than contributing hidden zero-valued series. Selector queries return only visible resources and include the resolution time.

A selector uses current inventory membership. It is not a historical label join unless the query explicitly requests a supported historical inventory source.

Large queries

The service bounds series count and bucket count. An oversized request returns 422 query_too_large with the limiting dimension. Split time ranges or resource sets and preserve null buckets when merging results.

A metrics read does not force an agent to collect another sample. Use metrics and health for source interpretation and Alert rule API for sustained condition evaluation.