---
title: "Query a metric time series"
method: GET
path: "/v2/metrics/{metric_name}"
tags: ["CustomerMetrics"]
---

# Query a metric time series

`GET /v2/metrics/{metric_name}`

Returns a time series of aggregated metric values for the named metric within the requested time range.

## Path parameters

- `metric_name` string, required

## Query parameters

- `labels` object
- `start` string, date-time, required
- `end` string, date-time, required
- `max_bins` integer

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

The requested metric series.

- union — A time series of metric points. The shape of points varies by metric type.
  - object — Common properties shared by all metric series types.
    - `metric_name` string, required — The name of the metric this series describes.
    - `labels` object, required — The labels matched for this series. Echoes the filter values supplied in the request.
    - `bin_size_seconds` integer, required — The width of each time bin in the returned series, in seconds. The platform chooses it from the requested time range and `max_bins`.
    - `type` string, required
    - `points` ScalarMetricPoint[], required
      - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). End-time aligned.
      - `value` number, double, required — The aggregated value for this time bin.
  - object — Common properties shared by all metric series types.
    - `metric_name` string, required — The name of the metric this series describes.
    - `labels` object, required — The labels matched for this series. Echoes the filter values supplied in the request.
    - `bin_size_seconds` integer, required — The width of each time bin in the returned series, in seconds. The platform chooses it from the requested time range and `max_bins`.
    - `type` string, required
    - `points` ScalarMetricPoint[], required
      - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). End-time aligned.
      - `value` number, double, required — The aggregated value for this time bin.
  - object — Common properties shared by all metric series types.
    - `metric_name` string, required — The name of the metric this series describes.
    - `labels` object, required — The labels matched for this series. Echoes the filter values supplied in the request.
    - `bin_size_seconds` integer, required — The width of each time bin in the returned series, in seconds. The platform chooses it from the requested time range and `max_bins`.
    - `type` string, required
    - `points` PercentilesMetricPoint[], required
      - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). End-time aligned.
      - `percentiles` PercentileEntry[], required — Per-percentile aggregated values for this time bin. Each entry's `value` is the metric's aggregated value at the percentile identified by `label`.
        - `label` string, required — The stable identifier for this percentile (e.g. `p50`, `p99`).
        - `value` number, double, required — The numeric value — the percentile rank on the descriptor, the aggregated value on a response point.
  - object — Common properties shared by all metric series types.
    - `metric_name` string, required — The name of the metric this series describes.
    - `labels` object, required — The labels matched for this series. Echoes the filter values supplied in the request.
    - `bin_size_seconds` integer, required — The width of each time bin in the returned series, in seconds. The platform chooses it from the requested time range and `max_bins`.
    - `type` string, required
    - `points` DistributionMetricPoint[], required
      - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). End-time aligned.
      - `bins` HistogramBin[], required — Per-bin counts for this time bin, sorted by the descriptor's canonical bin order.
        - `label` string, required — The bin label matching one of the labels declared on the metric's descriptor.
        - `value` integer, required — The count of observations whose value fell in this bin for this time window.

## Other responses

- `400` — Invalid request parameters.
- `404` — The named metric is not registered.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/a95087fe3a20/schema)