Статистика: звіти та експорт

Statistics API повертає агреговані звіти трекера — метрики × групування × фільтри за період. Це ті ж дані, що показує Конструктор звітів в кабінеті. Підходить для BI-систем, регулярних вивантажень та зовнішніх дашбордів.

Ключі метрик, групувань та фільтруваних полів зібрані в статті Статистика: довідник полів. Отримання токена, загальний формат відповідей та помилок — в головній статті розділу.

Скоупи

Усі операції вимагають права запиту статистики — воно є у всіх ролей. BUYER бачить тільки свою статистику, TEAM_LEAD — статистику команди з урахуванням налаштувань доступу до ресурсів, TEAM_OWNER та TECH — команду, ADMIN — все.

Ендпойнти

Базовий префікс — /api/stats. Тіло запитів — JSON, відповіді — application/json (для експорту — text/csv).

Для /api/stats/** діє окремий ліміт частоти — 3 запити на секунду з одного IP (burst 10). Понад ліміт шлюз відповідає 429.

POST /api/stats/query

Тіло запиту (StatsQueryDto):

{
  "time": {
    "preset": "last7",            // АБО from/to
    "from":  "2026-05-01 00:00:00",
    "to":    "2026-05-20 23:59:59",
    "timezone": "UTC"
  },
  "groups":  ["day", "cmp_campaign"],
  "metrics": ["clicks", "cpa_accept", "revenue", "roi"],
  "filters": [
    { "field": "user_country", "op": "in", "value": ["US", "CA"] },
    { "field": "cmp_offer",    "op": "eq", "value": "65f0…" }
  ],
  "pagination": { "page": 1, "limit": 100 },
  "sort": { "field": "clicks", "order": "desc" },
  "attributionWindow": { "hours": 24, "eventType": "click" }
}

Поля запиту

time (TimeRangeDto)

Потрібно передати або preset, або from (опціонально з to).

filters[] (FieldFilterDto)

Кожен фільтр — { "field", "op", "value" }. Поле повинно входити в список GET /api/stats/meta/filters.

Серверні фільтри. Поля cmp_team та cmp_user завжди перевизначаються сервером відповідно до ролі власника токена: задане клієнтом значення cmp_team ігнорується, а cmp_user перетинається з дозволеним набором користувачів. Обмежити звіт чужими даними через API неможливо.

Правила

• groups та metrics приймають тільки ключі з довідників; невідомий ключ — помилка 422.
• Якщо у групування є «name»-варіант (cmp_campaign ↔ cmp_campaign_name), він додається в рядки автоматично — передавати його окремо не потрібно.
• attributionWindow впливає тільки на метрики Push Attribution (push_postclick_*); без нього ці метрики повернуть нулі.
• Метрики LTV/Cohort (ltv_*, ftds, registrations…) використовуються разом з групуваннями cohort_*, reg_cohort_*, lifetime_days*.
• Для query рекомендується limit ≤ 10 000; для повного вивантаження використовуйте CSV.

Приклад відповіді

{
  "data": {
    "rows": [
      {
        "day": "2026-05-13T00:00:00+00:00",
        "cmp_campaign": "65f0…",
        "cmp_campaign_name": "Brand A — RU",
        "clicks": 18432,
        "cpa_accept": 122,
        "revenue": 2840.55,
        "roi": 0.36
      }
    ],
    "total": { "clicks": 18432, "cpa_accept": 122, "revenue": 2840.55 },
    "page": 1,
    "limit": 100,
    "rowCount": 1
  },
  "traceId": "01HX…"
}

rows — рядки звіту (ключі групувань + метрики), total — підсумок по всій вибірці без урахування пагінації, rowCount — кількість рядків на поточній сторінці. Частки (roi, click_to_dep тощо) приходять як числа в діапазоні 0..1, гроші — в USD.

POST /api/stats/export/csv

Те ж тіло StatsQueryDto. Відповідь — text/csv; charset=utf-8, ім'я файлу stats-report-YYYY-MM-DD.csv. Пагінація ігнорується, вивантаження обмежене 100 000 рядків.

curl -X POST 'https://adset.pro/api/stats/export/csv' \
  -H 'Authorization: Bearer pat_…' \
  -H 'Content-Type: application/json' \
  --data-binary @query.json -o report.csv

Довідники GET /api/stats/meta/*

Довідники — живе джерело ключів: якщо в платформі з'явилася нова метрика, вона відразу є в meta/metrics. Відповіді мають вигляд { "data": [ … ], "traceId" }; кешуйте їх на стороні інтеграції.

meta/metrics

{
  "key": "roi",
  "type": "calculated",
  "title": "ROI",
  "group": "Finance",
  "format": "percent",
  "dependencies": ["revenue", "cost"],
  "table": "events"
}

type — direct (прямий агрегат) або calculated (обчислюється з dependencies); format — підказка для форматування: ceil (ціле), finance (гроші), percent (частка 0..1), number; table — таблиця ClickHouse, в якій метрика існує.

meta/groups

{ "key": "cmp_campaign", "title": "Campaign", "group": "Campaign", "tables": ["events", "events_push", "events_push_attributed"] }

tables — в яких таблицях групування валідне; групування та метрики в одному запиті повинні перетинатися хоча б по одній таблиці.

meta/filters

{ "field": "user_country", "type": "list", "group": "Traffic", "name": "Country" }

meta/distinct

Підказки значень поля: GET /api/stats/meta/distinct?field=user_country&q=us&limit=20. Поле повинно входити в meta/filters.

{
  "data": [
    { "label": "US", "value": "US" },
    { "label": "Australia", "value": "AU" }
  ],
  "traceId": "01HX…"
}

Для сутностей (cmp_campaign, cmp_offer, cmp_cpa…) value — це ObjectId, label — ім'я. Цей же ендпойнт зручно використовувати, щоб знайти id для фільтра за назвою.

meta/os-versions

Те ж, що distinct?field=user_os_ver, але з додатковою нормалізацією версій ОС.

Приклади

Звіт по дням та кампаніям за минулий тиждень

curl -X POST 'https://adset.pro/api/stats/query' \
  -H 'Authorization: Bearer pat_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": { "preset": "prevWeek", "timezone": "Europe/Moscow" },
    "groups": ["day", "cmp_campaign"],
    "metrics": ["clicks", "cpa_accept", "revenue", "roi"],
    "filters": [
      { "field": "user_country", "op": "in", "value": ["US","CA","GB"] }
    ],
    "pagination": { "page": 1, "limit": 50 },
    "sort": { "field": "revenue", "order": "desc" }
  }'

Підказки по країнам

curl -G 'https://adset.pro/api/stats/meta/distinct' \
  -H 'Authorization: Bearer pat_…' \
  --data-urlencode 'field=user_country' \
  --data-urlencode 'q=u' \
  --data-urlencode 'limit=10'

LTV-когорта по тижнях

curl -X POST 'https://adset.pro/api/stats/query' \
  -H 'Authorization: Bearer pat_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": { "preset": "last30" },
    "groups": ["cohort_week", "lifetime_days"],
    "metrics": ["ftds", "ltv_d0", "ltv_d1_7", "ltv_d8_30", "ltv_total", "ltv_per_ftd"],
    "pagination": { "page": 1, "limit": 1000 }
  }'

Push Attribution з вікном 48 годин

curl -X POST 'https://adset.pro/api/stats/query' \
  -H 'Authorization: Bearer pat_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": { "preset": "last7" },
    "groups": ["day", "event_push_id"],
    "metrics": ["push_views", "push_clicks", "push_postclick_accepts", "push_click_to_accept_rate"],
    "attributionWindow": { "hours": 48, "eventType": "click" }
  }'

Експорт CSV

curl -X POST 'https://adset.pro/api/stats/export/csv' \
  -H 'Authorization: Bearer pat_…' \
  -H 'Content-Type: application/json' \
  --data-binary @query.json -o report.csv

Помилки

Загальний формат помилок та коди 401/403 описані в головній статті розділу.

Пов'язані статті

• Статистика: довідник полів — всі ключі фільтрів, групувань та метрик
• Довідник метрик — що означає кожна метрика та як її читати
• MCP-сервіс Adset — ті ж звіти через LLM-клієнти