---
title: "Get Metric Breakdown Series"
method: GET
path: "/v1/metrics/{metric}/breakdown/series"
---

# Get Metric Breakdown Series

`GET /v1/metrics/{metric}/breakdown/series`

Per-value time series for the top-N values of a dimension — ONE scan.

Replaces the portal breakdown tables' per-row filtered /timeseries
fan-out (2 GETs x N rows per table) with a single grouped query:
GROUP BY (dimension, time bucket), restricted to the top-N dimension
values via a joined subquery (same selection logic/ordering as
/breakdown), so the window is scanned once — not once per value.

`values[]` (optional, <=100) overrides top-N selection with an explicit
value list; the response then contains one entry per requested value in
the given order, zero-filled when a value has no rows. The portal uses
this to request series for exactly the rows its /breakdown call returned
(whose top-N may have been computed over a different timeframe than the
fixed 7d/30d sparkline windows).

Bucketing matches /timeseries exactly: same granularity auto-selection,
same org-timezone day/hour keys, same gap-filling. Decomposable metrics
use the two-level 15-minute-bin machinery; unique_viewers/median run a
single-pass GROUP BY — per-(value, bucket) COUNT(DISTINCT) is exact
because each bucket is contained within one group.

## Path parameters

- `metric` string, required

## Query parameters

- `dimension` string, required
- `measurement` string, nullable
- `limit` integer
- `order_by` string

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/shortkit/apis/shortkit-api.md) · [All operations](https://skmtc.net/shortkit/apis/shortkit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shortkit/shortkit-api/versions/4ff6d068cf75/schema)