Статистика
Overview, series, breakdown, ranking и карточка ссылки.
GET /stats/{scope_id}/breakdown
Срез по одному измерению
Top-N (или full) распределение метрики по указанному `dimension`. Хвост может быть свёрнут в `(other)` (`include_other=true`, default). Отдельный запрос на каждый график дашборда — либо кеш на клиенте между тиками polling.
Действия
`dimension=short` (для scope/folder) обрабатывается через ranking-ручку — здесь отвергается (см. документацию contract'а).
Параметры пути
Query-параметры
Ответы
GET /stats/{scope_id}/overview
Overview scope/folder/short
Собирает **упакованный отчёт** для мини-дашборда: KPI + короткий series (day, до 5 точек) + top-N срезы + top-N shorts. Не рассчитан на polling — один запрос при открытии scope/folder/short или ручной refresh.
Действия
Ошибки не кешируются никогда. При недоступности Redis GET — fail-open (запрос идёт в Postgres). `folder_id` и `short_id` взаимоисключающие → иначе 400 `validation_error`.
Параметры пути
Query-параметры
Ответы
GET /stats/{scope_id}/ranking
Топ сущностей внутри entity
Упорядоченная таблица «топов»: ссылки / targets / UTM-кампании / referrers / countries с метриками за окно. Удобна для scope/folder overview tables и polling раз в ~60 с.
Действия
`folder_id` и `short_id` взаимоисключающие → иначе 400 `validation_error`.
Параметры пути
Query-параметры
Ответы
GET /stats/{scope_id}/series
Временной ряд под polling
Возвращает временной ряд `(t, metrics…)` с гранулярностью `hour` или `day`. Рассчитан на **polling** (клиент опрашивает раз в `stats_rate_limit.min_poll_interval`).
Действия
Ошибки в кеш **никогда не пишутся**. Сбой Redis GET — fail-open.
Параметры пути
Query-параметры
Ответы
GET /stats/{scope_id}/shorts/{short_id}
Карточка ссылки: lifetime + window
Детальный отчёт по одной ссылке: **lifetime** (`link_short_agg`) — всегда, даже через годы после удаления raw; **window** KPI — из raw внутри retention, из agg day-maps вне.
Действия
Не путать с `GET /shorts/{scope}` из модуля short — здесь только аналитика.
Параметры пути
Query-параметры
Ответы