--- 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, together with the metric's descriptor. ## Path parameters - `metric_name` string, required ## Query parameters - `dimensions` object - `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 metric query result. A single series of points whose shape 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. - `dimension_values` object, required — The dimension values identifying this series, keyed by dimension name. Echoes the `dimensions` filter supplied in the request. A dimension absent from the map was not filtered, so the series merges every value of it. - `labels` object, required — Deprecated alias for `dimension_values`; identical value. Use `dimension_values`. - `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`. When `max_bins` is 1, it is the width of the requested window after rounding `start` down and `end` up to the nearest five-minute boundary. - `metric` union, required — Metadata about a registered metric. `type` selects the concrete variant. - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `percentiles` PercentileEntry[], required — The percentile entries this metric returns, in canonical order. Each entry's `label` matches a corresponding entry in every response point's `percentiles` array; `value` is the percentile rank (e.g. `0.5` for p50). - `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 metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `bins` DistributionBinDescriptor[], required — The bins this distribution may emit, in canonical order. Each bin has a stable label, an inclusive lower bound, and an exclusive upper bound (omitted for the overflow bin). - `label` string, required — The stable identifier for this bin. Response points reference it by `HistogramBin.label`. - `range_min` number, double, required — The inclusive lower bound of this bin's numeric range, in the metric's `unit`. - `range_max` number, double — The exclusive upper bound of this bin's numeric range, in the metric's `unit`. Omitted for the overflow bin. - `type` string, required - `points` ScalarMetricPoint[], required - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). Bins lie on a grid of `bin_size_seconds` anchored at the Unix epoch, except when `max_bins` is 1, where the single bin starts at `start` rounded down to the nearest five-minute boundary. - `value` number, double, required — The aggregated value for this bin. - object — Common properties shared by all metric series types. - `metric_name` string, required — The name of the metric this series describes. - `dimension_values` object, required — The dimension values identifying this series, keyed by dimension name. Echoes the `dimensions` filter supplied in the request. A dimension absent from the map was not filtered, so the series merges every value of it. - `labels` object, required — Deprecated alias for `dimension_values`; identical value. Use `dimension_values`. - `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`. When `max_bins` is 1, it is the width of the requested window after rounding `start` down and `end` up to the nearest five-minute boundary. - `metric` union, required — Metadata about a registered metric. `type` selects the concrete variant. - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `percentiles` PercentileEntry[], required — The percentile entries this metric returns, in canonical order. Each entry's `label` matches a corresponding entry in every response point's `percentiles` array; `value` is the percentile rank (e.g. `0.5` for p50). - `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 metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `bins` DistributionBinDescriptor[], required — The bins this distribution may emit, in canonical order. Each bin has a stable label, an inclusive lower bound, and an exclusive upper bound (omitted for the overflow bin). - `label` string, required — The stable identifier for this bin. Response points reference it by `HistogramBin.label`. - `range_min` number, double, required — The inclusive lower bound of this bin's numeric range, in the metric's `unit`. - `range_max` number, double — The exclusive upper bound of this bin's numeric range, in the metric's `unit`. Omitted for the overflow bin. - `type` string, required - `points` ScalarMetricPoint[], required - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). Bins lie on a grid of `bin_size_seconds` anchored at the Unix epoch, except when `max_bins` is 1, where the single bin starts at `start` rounded down to the nearest five-minute boundary. - `value` number, double, required — The aggregated value for this bin. - object — Common properties shared by all metric series types. - `metric_name` string, required — The name of the metric this series describes. - `dimension_values` object, required — The dimension values identifying this series, keyed by dimension name. Echoes the `dimensions` filter supplied in the request. A dimension absent from the map was not filtered, so the series merges every value of it. - `labels` object, required — Deprecated alias for `dimension_values`; identical value. Use `dimension_values`. - `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`. When `max_bins` is 1, it is the width of the requested window after rounding `start` down and `end` up to the nearest five-minute boundary. - `metric` union, required — Metadata about a registered metric. `type` selects the concrete variant. - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `percentiles` PercentileEntry[], required — The percentile entries this metric returns, in canonical order. Each entry's `label` matches a corresponding entry in every response point's `percentiles` array; `value` is the percentile rank (e.g. `0.5` for p50). - `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 metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `bins` DistributionBinDescriptor[], required — The bins this distribution may emit, in canonical order. Each bin has a stable label, an inclusive lower bound, and an exclusive upper bound (omitted for the overflow bin). - `label` string, required — The stable identifier for this bin. Response points reference it by `HistogramBin.label`. - `range_min` number, double, required — The inclusive lower bound of this bin's numeric range, in the metric's `unit`. - `range_max` number, double — The exclusive upper bound of this bin's numeric range, in the metric's `unit`. Omitted for the overflow bin. - `type` string, required - `points` PercentilesMetricPoint[], required - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). Bins lie on a grid of `bin_size_seconds` anchored at the Unix epoch, except when `max_bins` is 1, where the single bin starts at `start` rounded down to the nearest five-minute boundary. - `percentiles` PercentileEntry[], required — Percentile values for this time bin. Entries appear in the same order and with the same labels as the descriptor's `percentiles` array. - `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. - `dimension_values` object, required — The dimension values identifying this series, keyed by dimension name. Echoes the `dimensions` filter supplied in the request. A dimension absent from the map was not filtered, so the series merges every value of it. - `labels` object, required — Deprecated alias for `dimension_values`; identical value. Use `dimension_values`. - `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`. When `max_bins` is 1, it is the width of the requested window after rounding `start` down and `end` up to the nearest five-minute boundary. - `metric` union, required — Metadata about a registered metric. `type` selects the concrete variant. - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - object — Common metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `percentiles` PercentileEntry[], required — The percentile entries this metric returns, in canonical order. Each entry's `label` matches a corresponding entry in every response point's `percentiles` array; `value` is the percentile rank (e.g. `0.5` for p50). - `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 metadata fields shared by every metric descriptor regardless of type. - `name` string, required — The unique name of the metric, used as the path parameter to query it. Custom metric names start with `custom.`. - `category` string, required — The top-level grouping for this metric. - `description` string, required — A human-readable description of what the metric measures. - `unit` string — The unit of measure for the metric values, when applicable. - `display_name` string, required — A short human-readable name for this metric, suitable as a chart title or list label. - `dimensions` string[], required — The names of the dimensions this metric is broken down by. Filter on them with the `dimensions` query parameter when querying the metric. On a custom metric these are the dimension names declared in its definition. - `labels` string[], required — Deprecated alias for `dimensions`; identical value. Use `dimensions`. - `origin` 'system' | 'custom', required — Who provides a metric. New values may be added; treat unknown values as opaque. * `system`: the platform provides the metric. It cannot be updated or deleted. * `custom`: the account created the metric from its agent traces. - `type` string, required - `bins` DistributionBinDescriptor[], required — The bins this distribution may emit, in canonical order. Each bin has a stable label, an inclusive lower bound, and an exclusive upper bound (omitted for the overflow bin). - `label` string, required — The stable identifier for this bin. Response points reference it by `HistogramBin.label`. - `range_min` number, double, required — The inclusive lower bound of this bin's numeric range, in the metric's `unit`. - `range_max` number, double — The exclusive upper bound of this bin's numeric range, in the metric's `unit`. Omitted for the overflow bin. - `type` string, required - `points` DistributionMetricPoint[], required - `bin_start` string, date-time, required — The start of the time bin in ISO 8601 (UTC). Bins lie on a grid of `bin_size_seconds` anchored at the Unix epoch, except when `max_bins` is 1, where the single bin starts at `start` rounded down to the nearest five-minute boundary. - `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. - `422` — The metric's definition cannot be evaluated, so no series can be computed. ## Changes - **2026-09-23** `3f4075adad3d` — 2 info - added the media type `application/json` for the response with the status `400` - added the non-success response with the status `422` - **2026-09-16** `de6b34bc4a4f` — 14 info - added the new optional `query` request parameter `dimensions` - `query` request parameter `labels` was deprecated - response property `oneOf[#/components/schemas/CounterMetricSeries]/allOf[#/components/schemas/MetricSeriesBase]/labels` deprecated - response property `oneOf[#/components/schemas/DistributionMetricSeries]/allOf[#/components/schemas/MetricSeriesBase]/labels` deprecated - …10 more [Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/metrics/:metric_name/get.md) --- [API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/5cd882cb3cda?raw)