> 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. # Get aggregated metrics with time series for any aggregation level GET /v2/metrics Returns historical chart data for customer, node group, compute zone, or node level. This endpoint follows the v1/metrics/query_range pattern with a unified interface. Aggregation functions are determined by metric configuration in base-config.yaml. Reference: https://docs.nvidia.com/fleet-intel/fleet-intel/api-explorer/v-2-metrics/get-v-2-metrics ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: fleet-intelligence version: 1.0.0 paths: /v2/metrics: get: operationId: getV2Metrics summary: Get aggregated metrics with time series for any aggregation level description: >- Returns historical chart data for customer, node group, compute zone, or node level. This endpoint follows the v1/metrics/query_range pattern with a unified interface. Aggregation functions are determined by metric configuration in base-config.yaml. tags: - v2/metrics parameters: - name: groupBy in: query description: The aggregation level to group metrics by required: true schema: $ref: '#/components/schemas/V2MetricsGetParametersGroupBy' - name: groupId in: query description: >- The ID of the entity (required for nodegroup, computezone, node; not needed for customer level) required: false schema: type: string - name: metricNames in: query description: >- Comma-separated list of metric names to query (e.g., dcgm_fi_dev_gpu_util,cpu_used_percent,memory_used_percent) required: true schema: type: array items: type: string - name: startTime in: query description: >- Start time in RFC3339 format (required for absolute mode, e.g., 2024-01-01T00:00:00Z) required: false schema: type: string - name: endTime 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/V2MetricsGetParametersTimeMode' - name: window in: query description: >- Relative duration window (required for relative mode). Uses Go duration syntax — 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., 1m, 5m, 1h). Minimum step width is 1 minute. required: true schema: type: string responses: '200': description: Metrics with time series for the requested aggregation level content: application/json: schema: $ref: '#/components/schemas/models.MetricsAggregationResponse' '499': description: Client Closed Request - request was canceled by the client content: application/json: schema: $ref: '#/components/schemas/models.ErrorResponse' components: schemas: V2MetricsGetParametersGroupBy: type: string enum: - customer - nodegroup - computezone - node title: V2MetricsGetParametersGroupBy V2MetricsGetParametersTimeMode: type: string enum: - absolute - relative title: V2MetricsGetParametersTimeMode models.Aggregation: type: string enum: - average - sum - min - max - none title: models.Aggregation 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.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.MetricTimeSeries: type: object properties: aggregation: $ref: '#/components/schemas/models.Aggregation' displayName: type: string emptyStateMessage: type: string falseLabel: type: string description: >- FalseLabel is the human-readable label for value 0 in boolean/count-as-bool metrics. Omitted for non-boolean metrics. name: type: string result: type: array items: $ref: '#/components/schemas/models.MetricSeriesData' description: Array of series data (1 for aggregated, multiple for node-level) trueLabel: type: string description: >- TrueLabel is the human-readable label for value 1 in boolean/count-as-bool metrics. Omitted for non-boolean metrics. unit: type: string warning: $ref: '#/components/schemas/models.MetricQueryWarning' required: - warning title: models.MetricTimeSeries models.TimeRange: type: object properties: end: type: string format: date-time start: type: string format: date-time title: models.TimeRange models.MetricsAggregationResponse: type: object properties: metrics: type: array items: $ref: '#/components/schemas/models.MetricTimeSeries' step: type: string description: Query resolution step width from request timeRange: $ref: '#/components/schemas/models.TimeRange' title: models.MetricsAggregationResponse 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 { "metrics": [ { "warning": { "code": "invalidMetricValues", "message": "1 data point(s) had invalid values and were omitted." }, "aggregation": "average", "displayName": "GPU Utilization", "emptyStateMessage": "No error detected", "falseLabel": "Down", "name": "dcgm_fi_dev_gpu_util", "result": [ { "displayLabel": "GPU 0", "label": {}, "values": "[[1705276800, 0.723], [1705277100, 0.741]]" } ], "trueLabel": "Up", "unit": "ratio" } ], "step": "5m", "timeRange": { "end": "2024-01-01T01:00:00Z", "start": "2024-01-01T00:00:00Z" } } ``` **SDK Code** ```python import requests url = "https://api.example.com/v2/metrics" querystring = {"groupBy":"nodegroup","groupId":"550e8400-e29b-41d4-a716-446655440000","metricNames":"[\"dcgm_fi_dev_gpu_util,cpu_used_percent\"]","step":"5m","window":"24h"} response = requests.get(url, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.example.com/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h'; 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/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h" 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/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h") 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 response = Unirest.get("https://api.example.com/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h") .asString(); ``` ```php request('GET', 'https://api.example.com/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h'); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.example.com/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h"); var request = new RestRequest(Method.GET); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v2/metrics?groupBy=nodegroup&groupId=550e8400-e29b-41d4-a716-446655440000&metricNames=%5B%22dcgm_fi_dev_gpu_util%2Ccpu_used_percent%22%5D&step=5m&window=24h")! 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() ```