Home/Интеграции/Публичное HTTP API

Публичное HTTP API

Документ описывает, как сторонние интеграции (BI-системы, скрипты, дашборды) могут авторизоваться и получать данные статистики через публичное HTTP API платформы.

Базовый URL: https://adset.pro (production). Swagger UI: https://adset.pro/api/docs (OpenAPI 3.0).

TL;DR (чек-лист)

В UI кабинета (раздел API ключи) создайте PAT (Personal Access Token). Скопируйте токен сразу — он показывается только один раз.
Передавайте токен в каждом запросе заголовком Authorization: Bearer <token>.
Все публичные эндпойнты статистики живут под префиксом /api/stats/**.
Тело запроса для /api/stats/query — это StatsQueryDto (см. ниже).
Скоупы PAT разделены: api:stats (читать), api:stats:export (CSV-выгрузка), api:stats:meta (справочники).
Альтернатива PAT — OAuth 2.0 (Authorization Code + PKCE) через /oauth/authorize → /api/oauth/token. Discovery: /.well-known/oauth-authorization-server.

1. Аутентификация

1.1 Personal Access Token (PAT) — рекомендуется для скриптов

Префикс токена: pat_… (~64 символа). Подходит для серверных интеграций и curl.

Использование

curl -X POST 'https://adset.pro/api/stats/meta/metrics' \
  -H 'Authorization: Bearer pat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Префикс pat_ принимается только на путях /api/*. На /mcp нужен отдельный ключ типа mcp (префикс mcp_).

1.2 OAuth 2.0 (Authorization Code + PKCE) — для приложений

Параметр	Значение
Authorization endpoint	`GET /oauth/authorize?client_id=…&redirect_uri=…&response_type=code&scope=api:stats&code_challenge=…&code_challenge_method=S256&state=…`
Token endpoint	`POST /api/oauth/token` (`grant_type=authorization_code` или `refresh_token`)
Token prefix	`oat_…`
Discovery (RFC 8414)	`GET /.well-known/oauth-authorization-server`
Protected resource (RFC 9728)	`GET /.well-known/oauth-protected-resource`
Регистрация клиента	`POST /api/oauth/register` (RFC 7591 Dynamic Client Registration)

OAuth-токены oat_ принимаются и на /api/*, и на /mcp.

1.3 Скоупы доступа к API

Скоуп	Что разрешает
`api:stats`	`POST /api/stats/query` — читать агрегаты статистики
`api:stats:export`	`POST /api/stats/export/csv` — выгрузка CSV
`api:stats:meta`	`GET /api/stats/meta/*` — словари полей, метрик, групп

Эффективные права = скоупы токена ∩ RBAC-роль пользователя-владельца. BUYER видит только свою статистику, TEAM_LEAD — статистику команды по правилам resourceAccess и т.д.

1.4 Стандартные ошибки авторизации

HTTP	`error`	Причина
401	`invalid_token`	токен отсутствует / просрочен / отозван
401	`invalid_token_prefix`	`pat_` использован на `/mcp` или `mcp_` на `/api`
403	`insufficient_scope`	у токена нет требуемого scope (см. таблицу 1.3)
403	`forbidden`	RBAC-проверка пользователя не прошла

2. Эндпойнты публичного API статистики

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

Метод	Путь	Скоуп	Назначение
`POST`	`/api/stats/query`	`api:stats`	Получить отчёт (метрики × группировки + фильтры)
`POST`	`/api/stats/export/csv`	`api:stats:export`	Та же выборка, но в виде CSV (без пагинации, до 100 000 строк)
`GET`	`/api/stats/meta/metrics`	`api:stats:meta`	Каталог метрик
`GET`	`/api/stats/meta/groups`	`api:stats:meta`	Каталог группировок
`GET`	`/api/stats/meta/filters`	`api:stats:meta`	Список фильтруемых полей
`GET`	`/api/stats/meta/distinct?field=&q=&limit=`	`api:stats:meta`	Подсказки (autocomplete) для значения поля
`GET`	`/api/stats/meta/os-versions?q=&limit=`	`api:stats:meta`	Подсказки для версий ОС

2.1 `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"],     // см. Раздел 5
  "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 обязателен; нужно передать либо preset, либо from (опционально с to).
groups — массив ключей из таблицы группировок (см. раздел 5). Пустой массив → агрегат «всего».
metrics — массив ключей метрик из раздела 6. По умолчанию ["clicks"].
filters[*].op — оператор из таблицы 4.1.
pagination.limit ≤ 100 000 (фактический максимум API), для query рекомендуется ≤ 100.
attributionWindow применяется только к Push-метрикам (push_postclick_*).

Пример ответа

{
  "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…"
}

2.2 `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

2.3 `GET /api/stats/meta/metrics`

Возвращает список объектов вида:

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

2.4 `GET /api/stats/meta/groups`

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

2.5 `GET /api/stats/meta/filters`

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

2.6 `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…"
}

2.7 `GET /api/stats/meta/os-versions`

То же, что distinct?field=user_os_ver, но с дополнительной нормализацией версий.

3. Структура `StatsQueryDto`

Поле	Тип	Обяз.	Описание
`time`	`TimeRangeDto`	да	Временной интервал отчёта
`groups`	`GroupKey[]`	нет	Массив группировок (раздел 5)
`metrics`	`string[]`	нет	Массив ключей метрик (раздел 6). По умолчанию `["clicks"]`
`filters`	`FieldFilterDto[]`	нет	Массив фильтров (раздел 4)
`pagination`	`{page, limit}`	нет	`page ≥ 1`, `1 ≤ limit ≤ 100000` (default 100)
`sort`	`{field, order}`	нет	`order ∈ {asc, desc}`
`attributionWindow`	`{hours, eventType}`	нет	Окно атрибуции для Push-метрик: `1 ≤ hours ≤ 720`, `eventType ∈ {click, view}`

3.1 `TimeRangeDto`

Поле	Описание
`from`	`'YYYY-MM-DD HH:mm:ss'` или ISO 8601
`to`	то же
`timezone`	IANA TZ, по умолчанию `UTC`
`preset`	один из пресетов (раздел 3.2). Имеет приоритет над `from/to`

3.2 Пресеты дат (`time.preset`)

Пресет	Что значит
`today`	Сегодня от 00:00 до текущего момента
`yesterday`	Полные предыдущие сутки
`last7`	Последние 7 полных дней (включая сегодня)
`last30`	Последние 30 полных дней
`thisWeek`	С понедельника текущей недели
`prevWeek`	Предыдущая полная неделя (Пн–Вс)
`thisMonth`	С 1-го числа текущего месяца
`prevMonth`	Предыдущий полный месяц

4. Фильтры

4.1 Операторы (`FieldFilterDto.op`)

Оператор	Семантика	Тип `value`
`eq`	равно	строка/число
`neq`	не равно	строка/число
`in`	значение из списка	массив
`not_in`	значения нет в списке	массив
`gt`	больше	число
`lt`	меньше	число
`gte`	больше или равно	число
`lte`	меньше или равно	число
`between`	в диапазоне	`[min, max]` массив из 2 элементов
`like`	подстрока (case-insensitive, ClickHouse `ILIKE`)	строка с `%`

4.2 Серверные фильтры (нельзя задавать клиентом)

Поля cmp_team и cmp_user всегда переопределяются сервером согласно роли пользователя — попытка задать их клиентом игнорируется (для cmp_user — пересекается с разрешённым набором, см. раздел 1.3).

4.3 Полный список фильтруемых полей

Поле	Имя	Группа
`user_device`	Device	Traffic
`user_platform`	Platform	Traffic
`user_os`	OS	Traffic
`user_os_ver`	OS Version	Traffic
`user_browser`	Browser	Traffic
`user_browser_ver`	Browser Version	Traffic
`user_lang`	Language	Traffic
`user_country`	Country	Traffic
`user_region`	Region	Traffic
`user_asn`	ASN	Traffic
`user_asn_org`	ASN Org	Traffic
`user_ip`	IP	Traffic
`event_domain`	Domain	Event
`event_click_id`	Click ID	Event
`event_type`	Event Type	Event
`ext_utm_source`	UTM Source	UTM
`ext_utm_campaign`	UTM Campaign	UTM
`ext_utm_medium`	UTM Medium	UTM
`ext_utm_content`	UTM Content	UTM
`ext_utm_term`	UTM Term	UTM
`ext_sub1`	Sub1	UTM
`ext_sub2`	Sub2	UTM
`ext_sub3`	Sub3	UTM
`ext_sub4`	Sub4	UTM
`ext_sub5`	Sub5	UTM
`ext_sub6`	Sub6	UTM
`ext_sub7`	Sub7	UTM
`ext_sub8`	Sub8	UTM
`ext_sub9`	Sub9	UTM
`ext_sub10`	Sub10	UTM
`cmp_user`	User	Stream
`cmp_team`	Team	Stream
`cmp_campaign`	Campaign	Stream
`cmp_cpa`	CPA	Stream
`cmp_offer`	Offer	Stream
`cmp_offer_type`	Offer type	Stream
`cmp_flow`	Flow	Stream
`cmp_creative`	Creative	Stream
`cmp_pwa`	PWA	Stream
`cmp_landing`	Landing	Stream
`cmp_source`	Source	Stream
`cmp_set`	Set	Stream
`cmp_rotation`	Rotation	Stream
`event_push_id`	Push ID	Push
`event_slot_key`	Slot Key	Push
`event_sub_id`	Sub ID	Push

Для значений-перечислений (страны, ОС, кампании и т.п.) удобно использовать GET /api/stats/meta/distinct?field=…&q=… — он вернёт пары {label, value}.

5. Группировки (`groups[]`)

Если рядом с ID-полем существует «name»-вариант (cmp_campaign ↔ cmp_campaign_name), его не нужно явно добавлять — он подмешивается в проекцию автоматически.

tables — типы ответов для которых группировка валидна:

events — основная воронка (clicks, conversions, finance);
events_push — Push-события;
events_push_attributed — Post-click атрибуция Push;
events_ltv — LTV / Cohort.

5.1 Время

Ключ	Заголовок	Группа	Таблицы
`hour`	Hour	Time	events, events_push, events_push_attributed
`hourTime`	Hour (DateTime)	Time	events, events_push, events_push_attributed
`day`	Day	Time	events, events_push, events_push_attributed
`week`	Week	Time	events, events_push, events_push_attributed
`month`	Month	Time	events, events_push, events_push_attributed

5.2 Cohort / LTV

Ключ	Заголовок	Группа	Таблицы
`cohort_day`	Cohort (Day)	Cohort	events_ltv
`cohort_week`	Cohort (Week)	Cohort	events_ltv
`cohort_month`	Cohort (Month)	Cohort	events_ltv
`lifetime_days`	Lifetime Days	Cohort	events_ltv
`reg_cohort_day`	Reg Cohort (Day)	Cohort	events_ltv
`reg_cohort_week`	Reg Cohort (Week)	Cohort	events_ltv
`reg_cohort_month`	Reg Cohort (Month)	Cohort	events_ltv
`lifetime_days_from_reg`	Lifetime Days (Reg)	Cohort	events_ltv

5.3 Пользователь / Сеть

Ключ	Заголовок	Группа	Таблицы
`user_device`	Device	User	events, events_push, events_push_attributed
`user_platform`	Platform	User	events, events_push, events_push_attributed
`user_os`	OS	User	events, events_push, events_push_attributed
`user_os_ver`	OS Version	User	events, events_push, events_push_attributed
`user_browser`	Browser	User	events, events_push, events_push_attributed
`user_browser_ver`	Browser Version	User	events, events_push, events_push_attributed
`user_lang`	Language	User	events, events_push, events_push_attributed
`user_lang_name`	Language Name	User	events, events_push, events_push_attributed
`user_country`	Country	User	events, events_push, events_push_attributed
`user_country_name`	Country Name	User	events, events_push, events_push_attributed
`user_region`	Region	User	events, events_push, events_push_attributed
`user_proxy`	Proxy	User	events, events_push, events_push_attributed
`user_proxy_type`	Proxy Type	User	events, events_push, events_push_attributed
`user_proxy_usage`	Proxy Usage	User	events, events_push, events_push_attributed
`user_bot`	Is Bot	User	events, events_push, events_push_attributed
`user_asn`	ASN	Network	events, events_push, events_push_attributed
`user_asn_org`	ASN Org	Network	events, events_push, events_push_attributed
`event_domain`	Domain	User	events

5.4 Маркетинг (UTM / External / Campaign)

Ключ	Заголовок	Группа	Таблицы
`ext_utm_source`	UTM Source	UTM	events
`ext_utm_campaign`	UTM Campaign	UTM	events
`ext_utm_medium`	UTM Medium	UTM	events
`ext_utm_content`	UTM Content	UTM	events
`ext_utm_term`	UTM Term	UTM	events
`ext_sub1` … `ext_sub10`	Sub 1 … Sub 10	External	events
`cmp_user`	Campaign Owner ID	Campaign	events, events_push, events_push_attributed
`cmp_user_name`	Campaign Owner Name	Campaign	events, events_push, events_push_attributed
`cmp_user_email`	Campaign Owner Email	Campaign	events, events_push, events_push_attributed
`cmp_campaign`	Campaign ID	Campaign	events, events_push, events_push_attributed
`cmp_campaign_name`	Campaign Name	Campaign	events, events_push, events_push_attributed
`cmp_cpa`	CPA ID	Campaign	events, events_push, events_push_attributed
`cmp_cpa_name`	CPA Name	Campaign	events, events_push, events_push_attributed
`cmp_offer`	Offer ID	Campaign	events, events_push, events_push_attributed
`cmp_offer_name`	Offer Name	Campaign	events, events_push, events_push_attributed
`cmp_flow`	Flow Link ID	Campaign	events, events_push, events_push_attributed
`cmp_flow_name`	Flow Name	Campaign	events, events_push, events_push_attributed
`cmp_pwa`	PWA ID	Campaign	events, events_push, events_push_attributed
`cmp_pwa_name`	PWA Name	Campaign	events, events_push, events_push_attributed
`cmp_landing`	Landing ID	Campaign	events, events_push, events_push_attributed
`cmp_landing_name`	Landing Name	Campaign	events, events_push, events_push_attributed
`cmp_source`	Traffic Source ID	Campaign	events, events_push, events_push_attributed
`cmp_source_name`	Traffic Source Name	Campaign	events, events_push, events_push_attributed
`cmp_set`	Campaign Stream Set ID	Campaign	events, events_push, events_push_attributed
`cmp_rotation`	Campaign Stream Set Rotation ID	Campaign	events, events_push, events_push_attributed

5.5 Push / Event

Ключ	Заголовок	Группа	Таблицы
`event_push_id`	Push ID	Push	events_push, events_push_attributed
`event_push_id_name`	Push Name	Push	events_push, events_push_attributed
`event_slot_key`	Slot Key	Push	events_push, events_push_attributed
`event_sub_id`	Sub ID	Push	events_push, events_push_attributed
`event_type`	Event Type	Event	events

6. Метрики (`metrics[]`)

type различает прямые агрегаты (direct) и вычисляемые из других метрик (calculated). У calculated в dependencies перечислены метрики, которые автоматически добавляются в ответ.

format — подсказка для фронтовых форматтеров: ceil (целое), finance (деньги, USD), percent (доля 0..1).

6.1 Трафик и финансы

Ключ	Заголовок	Группа	Тип	Формат	Зависимости / Описание
`clicks`	Clicks	Traffic	direct	ceil	Уникальные клики (по паре `user_ip + user_ua`) с `event_type = SOURCE_CLICK`
`click_all`	Clicks All	Traffic	direct	ceil	Все клики без дедупликации
`filter`	Filtered	Traffic	direct	ceil	События `SOURCE_FILTER` (отфильтрованный трафик, не попавший не в один из стримсетов кампании)
`cpc`	CPC	Traffic	calculated	finance	`cost / clicks`
`rpm`	RPM	Traffic	calculated	finance	`cost / clicks * 1000`
`cost`	Costs	Finance	direct	finance	Сумма `event_cost` по `SOURCE_CLICK` (закупка трафика)
`revenue`	Revenue	Finance	direct	finance	Сумма `event_revenue` (с конвертацией в USD)
`profit`	Profit	Finance	calculated	finance	`revenue - cost`
`roi`	ROI	Finance	calculated	percent	`(revenue - cost) / cost`
`epl`	EPL	Finance	calculated	finance	`revenue / cpa_accept` (Earning per Lead)
`epc`	EPC	Finance	calculated	finance	`revenue / clicks` (Earning per Click)
`cpl`	CPL	Finance	calculated	finance	`cost / cpa_accept`
`epl_total`	EPL Total	Finance	calculated	finance	`revenue / total_deposits`
`cpl_total`	CPL Total	Finance	calculated	finance	`cost / total_deposits`

6.2 Лендинг

Ключ	Заголовок	Группа	Тип	Формат	Описание
`land_views`	Impression	Landing	direct	ceil	События `LAND_VIEW`
`land_clicks`	Clicks	Landing	direct	ceil	События `LAND_CLICK`
`land_view_to_click_rate`	CTR	Landing	calculated	percent	`land_clicks / land_views`

6.3 PWA

Ключ	Заголовок	Группа	Тип	Формат	Описание
`pwa_views`	Impression	PWA	direct	ceil	`PWA_VIEW`
`pwa_installs`	Install	PWA	direct	ceil	`PWA_INSTALL`
`pwa_opens`	Open	PWA	direct	ceil	`PWA_OPEN`
`ios_installs`	iOS Install	PWA	direct	ceil	`IOS_INSTALL`
`click_to_instal_rate`	Click 2 Install	PWA	calculated	percent	`pwa_installs / clicks`
`click_to_ios_install_rate`	Click 2 iOS Install	PWA	calculated	percent	`ios_installs / clicks`
`pwa_view_to_instal_rate`	Imp 2 Install	PWA	calculated	percent	`pwa_installs / pwa_views`

6.4 Postlanding

Ключ	Заголовок	Группа	Тип	Формат	Описание
`postlanding_views`	Impression	Postlanding	direct	ceil	`POSTLANDING_VIEW`
`postlanding_clicks`	Clicks	Postlanding	direct	ceil	`POSTLANDING_CLICK`
`postlanding_ctr`	CTR	Postlanding	calculated	percent	`postlanding_clicks / postlanding_views`

6.5 Notify

Ключ	Заголовок	Группа	Тип	Формат	Описание
`notify_requests`	Notify requests	Notify	direct	ceil	`NOTIFICATION_REQUEST`
`notify_subscribes`	Notify subscribes	Notify	direct	ceil	`NOTIFICATION_SUBSCRIBE`
`notify_declines`	Notify declines	Notify	direct	ceil	`NOTIFICATION_DECLINE`
`notify_click`	Clicks	Notify	direct	ceil	`NOTIFICATION_CLICK`

6.6 Конверсии

Ключ	Заголовок	Группа	Тип	Формат	Описание
`cpa_hold`	Registration	Conversion	direct	ceil	`CPA_HOLD` (регистрации)
`cpa_accept`	FTDs	Conversion	direct	ceil	`CPA_ACCEPT` (первые депозиты)
`cpa_decline`	DECLINE	Conversion	direct	ceil	`CPA_DECLINE`
`cpa_trash`	TRASH	Conversion	direct	ceil	`CPA_TRASH`
`cpa_redep`	Re-Deposits	Conversion	direct	ceil	`CPA_REDEP`
`cpa_accept_revenue`	FTD Revenue	Conversion	direct	finance	Доход с FTD
`cpa_redep_revenue`	ReDep Revenue	Conversion	direct	finance	Доход с повторных депов
`total_deposits`	Total Deposits	Conversion	calculated	ceil	`cpa_accept + cpa_redep`
`total_deposit_revenue`	Total Dep Revenue	Conversion	calculated	finance	`cpa_accept_revenue + cpa_redep_revenue`
`dep_to_redep`	Dep 2 ReDep	Conversion	calculated	percent	`cpa_redep / cpa_accept`
`click_to_reg`	Click 2 Reg	Conversion	calculated	percent	`cpa_hold / clicks`
`click_to_dep`	Click 2 Dep	Conversion	calculated	percent	`cpa_accept / clicks`
`click_to_dep_total`	Click 2 Dep Total	Conversion	calculated	percent	`total_deposits / clicks`
`pwa_install_to_hold_rate`	Install 2 Reg	Conversion	calculated	percent	`cpa_hold / pwa_installs`
`pwa_install_to_accept_rate`	Install to FTDs	Conversion	calculated	percent	`cpa_accept / pwa_installs`
`cpa_hold_to_accept_rate`	Reg 2 Dep	Conversion	calculated	percent	`cpa_accept / cpa_hold`

6.7 Telegram

Ключ	Заголовок	Группа	Тип	Формат	Описание
`tg_starts`	TG Starts	Telegram	direct	ceil	`TG_START`
`tg_joins`	TG Joins	Telegram	direct	ceil	`TG_JOIN`
`click_to_tg_start_rate`	Click 2 Start	Telegram	calculated	percent	`tg_starts / clicks`
`click_to_tg_join_rate`	Click 2 Join	Telegram	calculated	percent	`tg_joins / clicks`

6.8 Push (таблица `events_push`)

Ключ	Заголовок	Группа	Тип	Формат	Описание
`push_views`	Push Views	Push	direct	ceil	Просмотры push
`push_clicks`	Push Clicks	Push	direct	ceil	Клики по push
`push_ctr`	Push CTR	Push	calculated	percent	`push_clicks / push_views`

6.9 Push Attribution (таблица `events_push_attributed`)

Требует параметра attributionWindow в запросе.

Ключ	Заголовок	Группа	Тип	Формат	Описание
`push_postclick_holds`	Post-Click Registrations	Push Attribution	direct	ceil	Регистрации в окне атрибуции после push-клика
`push_postclick_accepts`	Post-Click FTDs	Push Attribution	direct	ceil	FTD после push-клика
`push_postclick_redeps`	Post-Click ReDeps	Push Attribution	direct	ceil	ReDep после push-клика
`push_click_to_hold_rate`	Click to Reg	Push Attribution	calculated	percent	`push_postclick_holds / push_clicks`
`push_click_to_accept_rate`	Click to FTD	Push Attribution	calculated	percent	`push_postclick_accepts / push_clicks`
`push_hold_to_accept_rate`	Reg to Dep	Push Attribution	calculated	percent	`push_postclick_accepts / push_postclick_holds`

6.10 LTV / Cohort (таблица `events_ltv`)

Используются вместе с группировками cohort_* / reg_cohort_* / lifetime_days* (раздел 5.2). LTV считается от даты FTD (ftd_time), Reg-LTV — от даты регистрации (reg_time).

Ключ	Заголовок	Группа	Тип	Формат	Описание
`avg_redep_revenue`	Avg ReDep Revenue	LTV	calculated	finance	`cpa_redep_revenue / cpa_redep`
`redep_per_ftd`	ReDeps per FTD	LTV	calculated	number	`cpa_redep / cpa_accept`
`redep_unique_clicks`	ReDep Users	LTV	direct	ceil	Уникальные `event_click_id` с ≥1 ReDep
`ftd_to_redep_rate`	FTD to ReDep Rate	LTV	calculated	percent	`redep_unique_clicks / cpa_accept`
`ltv_d0`	LTV Day 0	LTV	direct	finance	Доход за день FTD
`ltv_d1_7`	LTV Day 1-7	LTV	direct	finance	Доход в 1–7 день после FTD
`ltv_d8_30`	LTV Day 8-30	LTV	direct	finance	Доход в 8–30 день после FTD
`ltv_d31_90`	LTV Day 31-90	LTV	direct	finance	Доход в 31–90 день после FTD
`ltv_total`	LTV Total	LTV	calculated	finance	Сумма LTV окон от FTD
`ltv_per_ftd`	LTV per FTD	LTV	calculated	finance	`ltv_total / cpa_accept`
`ltv_reg_d0`	LTV Reg Day 0	LTV	direct	finance	Доход за день регистрации
`ltv_reg_d1_7`	LTV Reg Day 1-7	LTV	direct	finance	Доход в 1–7 день после регистрации
`ltv_reg_d8_30`	LTV Reg Day 8-30	LTV	direct	finance	Доход в 8–30 день после регистрации
`ltv_reg_d31_90`	LTV Reg Day 31-90	LTV	direct	finance	Доход в 31–90 день после регистрации
`ltv_reg_total`	LTV Reg Total	LTV	calculated	finance	Сумма LTV окон от регистрации
`ltv_per_reg`	LTV per Reg	LTV	calculated	finance	`ltv_reg_total / registrations`
`registrations`	Registrations	Cohort	direct	ceil	`CPA_HOLD` в когорте
`ftds`	FTDs	Cohort	direct	ceil	`CPA_ACCEPT` в когорте
`reg_to_ftd_rate`	Reg to FTD	Cohort	calculated	percent	`cpa_accept / cpa_hold`

7. Примеры (curl)

7.1 Получить отчёт по дням и кампаниям за прошлую неделю

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" }
  }'

7.2 Подсказки по странам

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'

7.3 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 }
  }'

7.4 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" }
  }'

7.5 Экспорт 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

8. Стандартные ошибки

HTTP	Тело	Когда
`400`	`{ "error": "time is required" }`	Не передан `time`
`400`	`{ "error": "time.preset or time.from/time.to required" }`	Некорректный временной интервал
`401`	`{ "error": "invalid_token", … }`	Токен битый/просрочен
`403`	`{ "error": "insufficient_scope" }`	Не хватает scope (см. 1.3)
`403`	`{ "error": "forbidden" }`	RBAC запрещает действие
`422`	стандартная схема `@tsed/schema`	Неверная форма JSON / `op` / `metric`

9. Лимиты и ограничения

Параметр	Лимит
`pagination.limit` (`/query`)	1 — 100 000 (рекомендовано ≤ 100 для UI, ≤ 10 000 для скриптов)
Экспорт CSV	до 100 000 строк
`attributionWindow.hours`	1 — 720 (30 дней)
Длина имени PAT	100 символов
Срок жизни PAT	задаётся при создании (`expiresInDays`), либо бессрочно

Синхронизация расходов Facebook через антидетект-агент (Spend Agent)Подтягивание расходов (костов) с Facebook в Adset pro Подтягивание расходов (костов) из TikTok в Adset pro Интеграция Adset.pro с сервисом клоакинга Veloraad.pro Как получить Facebook Dev Token для подключения рекламных кабинетов к Adset Pro Интеграция Adset pro с трекером Keitaro

Публичное HTTP API

TL;DR (чек-лист)

1. Аутентификация

1.1 Personal Access Token (PAT) — рекомендуется для скриптов

Использование

1.2 OAuth 2.0 (Authorization Code + PKCE) — для приложений

1.3 Скоупы доступа к API

1.4 Стандартные ошибки авторизации

2. Эндпойнты публичного API статистики

2.1 POST /api/stats/query

Правила

Пример ответа

2.2 POST /api/stats/export/csv

2.3 GET /api/stats/meta/metrics

2.4 GET /api/stats/meta/groups

2.5 GET /api/stats/meta/filters

2.6 GET /api/stats/meta/distinct

2.7 GET /api/stats/meta/os-versions

3. Структура StatsQueryDto

3.1 TimeRangeDto

3.2 Пресеты дат (time.preset)

4. Фильтры

4.1 Операторы (FieldFilterDto.op)

4.2 Серверные фильтры (нельзя задавать клиентом)

4.3 Полный список фильтруемых полей

5. Группировки (groups[])

5.1 Время

5.2 Cohort / LTV

5.3 Пользователь / Сеть

5.4 Маркетинг (UTM / External / Campaign)

5.5 Push / Event

6. Метрики (metrics[])

6.1 Трафик и финансы

6.2 Лендинг

6.3 PWA

6.4 Postlanding

6.5 Notify

6.6 Конверсии

6.7 Telegram

6.8 Push (таблица events_push)

6.9 Push Attribution (таблица events_push_attributed)

6.10 LTV / Cohort (таблица events_ltv)

7. Примеры (curl)

7.1 Получить отчёт по дням и кампаниям за прошлую неделю

7.2 Подсказки по странам

7.3 LTV-когорта по неделям

7.4 Push Attribution с окном 48 часов

7.5 Экспорт CSV

8. Стандартные ошибки

9. Лимиты и ограничения

2.1 `POST /api/stats/query`

2.2 `POST /api/stats/export/csv`

2.3 `GET /api/stats/meta/metrics`

2.4 `GET /api/stats/meta/groups`

2.5 `GET /api/stats/meta/filters`

2.6 `GET /api/stats/meta/distinct`

2.7 `GET /api/stats/meta/os-versions`

3. Структура `StatsQueryDto`

3.1 `TimeRangeDto`

3.2 Пресеты дат (`time.preset`)

4.1 Операторы (`FieldFilterDto.op`)

5. Группировки (`groups[]`)

6. Метрики (`metrics[]`)

6.8 Push (таблица `events_push`)

6.9 Push Attribution (таблица `events_push_attributed`)

6.10 LTV / Cohort (таблица `events_ltv`)