> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/fleet-intel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/fleet-intel/_mcp/server.

# Query metric range

GET /v1/metrics/query_range

Query data for a particular metric for a node, node group, or compute zone over a range of time

Reference: https://docs.nvidia.com/fleet-intel/fleet-intel/api-explorer/metrics/get-v-1-metrics-query-range

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: fleet-intelligence
  version: 1.0.0
paths:
  /v1/metrics/query_range:
    get:
      operationId: getV1MetricsQueryRange
      summary: Query metric range
      description: >-
        Query data for a particular metric for a node, node group, or compute
        zone over a range of time
      tags:
        - metrics
      parameters:
        - name: start
          in: query
          description: >-
            Start time in RFC3339 format (required for absolute mode, e.g.,
            2024-01-01T01:00:00Z). Cannot be more than 1 year in the past.
          required: false
          schema:
            type: string
        - name: end
          in: query
          description: >-
            End time in RFC3339 format (required for absolute mode, e.g.,
            2024-01-01T01:00:00Z)
          required: false
          schema:
            type: string
        - name: timeMode
          in: query
          description: Time mode for range selection. Defaults to absolute.
          required: false
          schema:
            $ref: '#/components/schemas/V1MetricsQueryRangeGetParametersTimeMode'
        - name: window
          in: query
          description: >-
            Relative duration window (required for relative mode). Valid units:
            h, m, s (e.g. 24h, 1h30m, 90m). 'd' is not supported; use hours
            instead (e.g. 168h for 7 days)
          required: false
          schema:
            type: string
        - name: step
          in: query
          description: >-
            Query resolution step width in duration format (e.g. 1h, 1m).
            Minimum step width is 1 minute.
          required: true
          schema:
            type: string
        - name: component
          in: query
          description: Component name (e.g., accelerator-nvidia-clock-speed)
          required: true
          schema:
            type: string
        - name: metric
          in: query
          description: >-
            Name of the metric to query (e.g.,
            accelerator_nvidia_clock_speed_graphics_mhz)
          required: true
          schema:
            type: string
        - name: entityLevel
          in: query
          description: >-
            The level of the entity to query for. In the future we intend to
            support aggregation across tags, node groups, and compute zones
          required: true
          schema:
            $ref: '#/components/schemas/V1MetricsQueryRangeGetParametersEntityLevel'
        - name: entityID
          in: query
          description: The ID of the compute zone, node group, or node
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Successful response" (NOTE: the result fields will be JSON objects
            and JSON arrays in the actual response, not strings)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.QueryMetricRangeResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '403':
          description: Forbidden - UAM authorization denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '499':
          description: Client Closed Request - request was canceled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
components:
  schemas:
    V1MetricsQueryRangeGetParametersTimeMode:
      type: string
      enum:
        - absolute
        - relative
      title: V1MetricsQueryRangeGetParametersTimeMode
    V1MetricsQueryRangeGetParametersEntityLevel:
      type: string
      enum:
        - node
      title: V1MetricsQueryRangeGetParametersEntityLevel
    models.MetricSeriesData:
      type: object
      properties:
        displayLabel:
          type: string
          description: >-
            DisplayLabel is the preferred label value for UI display (e.g., GPU
            index for DCGM metrics).

            Derived from the "gpu" key if present, otherwise falls back to
            "gpu_uuid".

            Omitted for aggregated levels where labels are not present.
        label:
          type: object
          additionalProperties:
            type: string
          description: >-
            Label contains identifying information (e.g., GPU UUID) for
            node-level queries.

            Omitted for aggregated levels (customer/nodegroup/computezone).

            Typical keys: "gpu" (GPU index), "uuid" (GPU UUID).
        values:
          type: string
          description: >-
            Values is a 2D array where each inner array contains
            [unix_timestamp, metric_value]

            This follows the Prometheus/Grafana standard format for
            compatibility

            The last element in the array represents the most recent/latest
            value

            Example: [[1705276800, 0.723], [1705277100, 0.741]]

            NOTE: swaggertype:"string" is a workaround for swag limitations with
            nested arrays
      title: models.MetricSeriesData
    models.TimeRange:
      type: object
      properties:
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
      title: models.TimeRange
    models.MetricQueryWarning:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      description: e.g. omitted invalid metric points; null when no issues
      title: models.MetricQueryWarning
    models.QueryMetricRangeResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/models.MetricSeriesData'
          description: >-
            NodeAggregationFunction string        
            `json:"nodeAggregationFunction" example:"avg"` // TODO: add this in
            later
        step:
          type: string
        stepAggregationFunction:
          type: string
        timeRange:
          $ref: '#/components/schemas/models.TimeRange'
        warning:
          $ref: '#/components/schemas/models.MetricQueryWarning'
      required:
        - warning
      title: models.QueryMetricRangeResponse
    models.KASRequestStatus:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID for tracing
        statusCode:
          type: string
          description: Status code from KAS
        statusDescription:
          type: string
          description: Status description from KAS
      description: >-
        RequestStatus contains KAS-specific error details

        This is added to reflect the field in OpenAPI docs for UI reference and
        not populated by our code

        If KAS returns an error, the request will not be forwarded to the
        backend
      title: models.KASRequestStatus
    models.ErrorResponse:
      type: object
      properties:
        details:
          type: string
          description: Detailed error information
        error:
          type: string
          description: Error message or type
        requestStatus:
          $ref: '#/components/schemas/models.KASRequestStatus'
      description: >-
        Standard error response returned by all API endpoints. For KAS API
        errors, requestStatus fields are populated.
      title: models.ErrorResponse

```

## Examples



**Response**

```json
{
  "warning": {
    "code": "invalidMetricValues",
    "message": "1 data point(s) had invalid values and were omitted."
  },
  "result": [
    {
      "displayLabel": "GPU 0",
      "label": {},
      "values": "[[1705276800, 0.723], [1705277100, 0.741]]"
    }
  ],
  "step": "5m",
  "stepAggregationFunction": "avg",
  "timeRange": {
    "end": "2024-01-01T01:00:00Z",
    "start": "2024-01-01T00:00:00Z"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/v1/metrics/query_range"

querystring = {"component":"component","entityID":"entityID","entityLevel":"node","metric":"metric","step":"step"}

response = requests.get(url, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step');

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/metrics/query_range?component=component&entityID=entityID&entityLevel=node&metric=metric&step=step")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```