---
title: "Range-query metrics (PromQL)"
method: POST
path: "/preview/metrics/queries"
tags: ["metrics"]
---

# Range-query metrics (PromQL)

`POST /preview/metrics/queries`

## Request

- Base URL: `https://autoresearch.sfcompute.com`
- URL: `https://autoresearch.sfcompute.com/preview/metrics/queries`
- Auth: HTTP bearer

PromQL over your org's metrics: platform telemetry, free and automatic - GPU (gmn_gpu_utilization, gmn_gpu_memory_used_bytes, gmn_gpu_power_watts, gmn_gpu_temperature_celsius), system per container (gmn_cpu_seconds_total, gmn_memory_used_bytes, gmn_memory_limit_bytes, gmn_network_receive_bytes_total, gmn_network_transmit_bytes_total), and spend (gmn_node_spend_usd, gmn_org_mtd_spend_usd) - labeled {node, mission} on nodes and {run, mission} on jobs, plus everything your registered scrapes collect. Range query; results are bounded and downsampled (at most 20 series x 200 points, truncated:true when cut) - ask narrower questions rather than paging. $mission/$run in the query substitute the matching params.

## Query parameters

- `workspace` string

## Request body

- object
  - `end` string, nullable: Range end, RFC3339 (default: now).
  - `mission` string, nullable: Substituted for `$mission` in the query.
  - `query` string, required: PromQL. `$mission` and `$run` substitute the params below, e.g. sum(rate(vllm:generation_tokens_total{mission="$mission"}[5m])).
  - `run` string, nullable: Substituted for `$run` in the query (a job-/cmd-/ses- scope id).
  - `start` string, nullable: Range start, RFC3339 (default: one hour before `end`).
  - `step_seconds` integer, nullable: Step seconds (default: the range divided into ~200 points).

## Response `200`

The capability's JSON result.

- Result: The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.
  - `object` string: The resource type, when the result is one resource.

## Other responses

- `400`: Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.
- `401`: No bearer token, or one this API cannot verify. Code `unauthenticated`.
- `403`: Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.
- `404`: No such route. Code `not_found`; the body names the OpenAPI document.
- `422`: A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.
- `429`: Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.
- `500`: Our fault. Retry; if it persists, quote the request-id. Code `internal`.

---

[API](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api.md) · [All operations](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/revisions/f88dcb70ac6c?raw)