Docs
Metrics

Query your instances' metrics over a time range

GET
/v1/prometheus/api/v1/query_range

Evaluates a PromQL query at every step from start to end, as Prometheus's GET /api/v1/query_range does, over your org's instance metrics and nothing else. The last 3 days are kept at 30 seconds and the last 14 days at 5 minutes; a range that starts more than 3 days ago is answered at 5 minutes.

Authorization

headerAuthorizationBearer <cc_...>

An API key of your org, sent as Authorization: Bearer cc_.... Keys start with cc_ and are otherwise opaque. Treat a key as a password: anyone holding it can act with its scopes until it expires or is revoked. Each operation's security requirement lists the scopes it needs; an empty list means any valid key. The MCP server at /mcp accepts agent keys and no other kind.

Scope: instances:read

Query Parameters

query*string

A PromQL expression, which may use VictoriaMetrics' MetricsQL extensions.

Length1 <= length <= 4096
start*string

The start of the range, as an RFC 3339 time or Unix seconds.

Length1 <= length <= 40
end*string

The end of the range, as an RFC 3339 time or Unix seconds.

Length1 <= length <= 40
step*string

The time between points, as a duration such as 30s or 5m, or seconds.

Length1 <= length <= 20
timeout?string

How long the query may run, as a duration such as 10s. At most, and by default, 20 seconds.

Length1 <= length <= 20

Header Parameters

Api-Version*string

The API version the request is written against. This document describes 2026-10-15. A missing header returns 400 api_version_required, and a version the API does not serve returns 400 unsupported_api_version.

X-Cloud-Organization?string

The Cloud organization whose metrics this data source requests. Required for the managed Grafana OAuth client, which forwards the querying user's WorkOS token with metrics:read:all-orgs. For that dedicated client and scope only, the API verifies the WorkOS issuer, audience and user, then checks current membership and read access in this requested org on every query. The token's org_id does not restrict this user-wide metrics grant. A missing, repeated or unauthorized org returns 403 insufficient_scope. Other callers may omit it; if provided, it must match the org their credential already authorizes. The header itself grants no access.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
X-Correlation-ID?string

An id of your own for this request, or for a group of requests, to find them in our logs and yours. Logged with the request and returned unchanged in X-Correlation-ID. The request id itself is always the API's own, in X-Request-ID.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin keys only: the id of the org to act in. Required with an admin key, together with Access-Reason; with any other credential it returns 400 invalid_request. Every request that carries it is recorded in that org's operator-access log.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin keys only: why the operator is acting in the org, such as a support ticket. Required with Org-Context. Recorded, verbatim, in the org's operator-access log.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Response Body

The query's result at each step, as Prometheus returns it.

application/json
  1. response

Prometheus's query result, which is why its shape is Prometheus's. Ignore fields you do not know.

status*string

success. Open set; accept values not listed.

data*

vector and matrix results are lists of series, each with its labels in metric and its value in value or its values in values. A scalar or string result is one [time, value] pair.

warnings?array<string>

Problems that did not stop the query, such as a result cut short.

Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/prometheus/api/v1/query_range?query=sum+by+%28instance%29+%28rate%28cloud_instance_cpu_seconds_total%5B5m%5D%29%29&start=2026-10-22T16%3A00%3A00Z&end=2026-10-22T17%3A00%3A00Z&step=30s&timeout=10s' \  -H 'Api-Version: 2026-10-15' \  -H 'X-Correlation-ID: rollout-2026-10-22' \  -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed'
Example Response
{  "status": "success",  "data": {    "resultType": "matrix",    "result": [      {        "metric": {          "instance": "i-7k2m9q4x1bfa"        },        "values": [          [            1792688340,            "18233.6"          ],          [            1792688370,            "20410.1"          ],          [            1792688400,            "19876.4"          ]        ]      }    ]  }}