Admin API: отчёты

Методы этой страницы строят те же отчёты, что конструктор отчётов в панели, и отдают данные по отдельным кликам. Авторизация описана на странице Admin API: обзор и авторизация, формат запросов и общие коды ошибок — на странице Формат запросов, ответов и ошибок.

Методы и права токена

• Токену Сводные отчёты (reports:read) доступны три метода: POST /api/v1/reports, POST /api/v1/reports/export и GET /api/v1/custom-metrics.
• Остальным 14 методам нужен Полный доступ (full).

Токен reports:read строит отчёт только по разрешённым группировкам и фильтрам. Их список — в разделе Ограничения доступа «Сводные отчёты». На отчёт с другими полями сервер отвечает 403 с кодом token_scope.

Фоновые выгрузки и сохранённые отчёты принадлежат пользователю, который создал токен. Через API видны и те, что он создал в панели.

Запрос отчёта

Одно и то же тело принимают три метода: POST /reports, POST /reports/export и POST /report-exports.

Часовой пояс задаёт границы часов, дней, недель и месяцев в группировках и день расхода. Что считается по дате клика, а что по дате конверсии — на странице Период, часовой пояс и атрибуция.

Группировки

• Значения группировок в ответе — всегда строки.
• В campaign, stream, offer, lander и source приходят идентификаторы, а не названия.
• Признаки приходят как 1 или 0.
• Неделя начинается с понедельника. В dow понедельник — 1, воскресенье — 7.
• Значение sub_id_12 не раскрывается: в строке *** или пусто.

Метрики

Встроенные метрики: clicks, unique_clicks, bots, lp_clicks, lp_ctr, leads, sales, rejected, conversions, cost, revenue, revenue_expected, profit, profit_expected, roi, roi_expected, cr, approval, cpa, epc, cpl. Формулы — на странице Метрики отчётов и формулы.

В metrics также можно передать:

• ключ своей метрики — поле name;
• колонку типа конверсии — cv_ и идентификатор типа без дефисов. Идентификаторы отдаёт GET /api/v1/conversion-types, см. Admin API: конверсии и постбек.

Суммы приходят числом в USD, проценты — числом без знака %.

Фильтры

Условие — объект из трёх строк:

Операторы зависят от вида поля:

• has и not_has проверяют, заполнено ли поле. Значение value не учитывается.
• У признака значения 0, false, no, off, нет и пустая строка означают «нет», любое другое — «да».
• У метрики value — конечное число.
• По группировкам времени фильтровать нельзя: период задают from и to.

Группа в filter_groups — объект {"mode": "or", "filters": [...]}. Поле mode принимает and или or, массив filters не может быть пустым. Группы связаны между собой и с filters через И. В группе or нельзя смешивать поля клика и метрики. Всего в запросе не больше 64 условий. Значения операторов и примеры — на странице Фильтры отчёта.

Сортировка

sort.field — одна из выбранных группировок либо метрика, встроенная или своя. sort.direction — asc или desc. Остальные группировки идут следом по возрастанию.

Построение отчёта

Построить отчёт

POST /api/v1/reports

Возвращает страницу отчёта и итоги по всем строкам. Права токена: reports:read или full. Тело — запрос отчёта. Отчёт строится не дольше 70 секунд.

Ответ — код 200:

Сверяйте timezone в ответе с запрошенным: если пояс недоступен на сервере, отчёт считается в UTC.

Чтобы получить следующую страницу, повторите запрос с offset, увеличенным на limit, пока has_more равно true.

Пример запроса:

curl -X POST https://panel.example.com/api/v1/reports \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-07T23:59:59Z",
    "timezone": "Europe/Warsaw",
    "dimensions": ["campaign", "country"],
    "metrics": ["clicks", "leads", "cost", "revenue", "roi"],
    "filters": [
      {"field": "bot", "op": "eq", "value": "0"},
      {"field": "clicks", "op": "gte", "value": "100"}
    ],
    "sort": {"field": "roi", "direction": "desc"},
    "limit": 100
  }'

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

{
  "columns": ["campaign", "country", "clicks", "leads", "cost", "revenue", "roi"],
  "rows": [
    ["c41a9e07-52bd-4f13-8a60-9d7e6f5a4b3c", "PL", 1520, 42, 310.5, 504, 62.318840579710144],
    ["7b0c1d52-3f4e-4a6b-9c8d-1e2f3a4b5c6d", "CZ", 830, 17, 190, 204, 7.368421052631579]
  ],
  "totals": {"clicks": 2350, "cost": 500.5, "leads": 59, "revenue": 708, "roi": 41.45854145854146},
  "truncated": false,
  "row_limit": 100,
  "total_rows": 2,
  "limit": 100,
  "offset": 0,
  "has_more": false,
  "attribution": "click",
  "timezone": "Europe/Warsaw"
}

Ошибки:

Получить отчёт файлом CSV

POST /api/v1/reports/export

Строит тот же отчёт и сразу отдаёт его файлом. Права токена: reports:read или full. Тело — запрос отчёта. Поля limit и offset на состав файла не влияют: в файл попадают все строки.

Ответ — код 200, тип text/csv; charset=utf-8, имя файла вида report-20261007-101500.csv. Первая строка — ключи колонок, строки итогов нет. Содержимое файла описано в разделе Что внутри CSV, колонки файла сравнения — в разделе CSV сравнения.

Пределы: 100 000 строк и 32 МиБ.

Ошибки те же, что у POST /reports, и ещё две:

Фоновые выгрузки CSV

Фоновая выгрузка строит тот же файл без ожидания ответа: запрос ставит отчёт в очередь, готовый файл хранится 24 часа с момента создания. Всем методам нужен доступ full. То же в панели — на странице Сохранённые отчёты и выгрузка CSV.

Объект выгрузки:

Создать выгрузку

POST /api/v1/report-exports

Ставит отчёт в очередь. Тело — запрос отчёта. Поле offset не учитывается, limit на состав файла не влияет. Атрибуция default фиксируется в момент запроса.

Ответ — код 202 и объект выгрузки в состоянии pending.

Список выгрузок

GET /api/v1/report-exports

Возвращает неистёкшие выгрузки создателя токена: массив объектов, до 20, новые первыми. Параметров нет. Опрашивайте список, пока state нужной выгрузки не станет ready или failed.

Скачать файл

GET /api/v1/report-exports/{id}/file

Отдаёт готовый файл: код 200, тип text/csv; charset=utf-8, имя report-<id>.csv. Параметр пути id — идентификатор выгрузки.

curl https://panel.example.com/api/v1/report-exports/5e2f8a10-9b3c-4d7e-8f21-0a1b2c3d4e5f/file \
  -H "Api-Key: <токен>" \
  -o report.csv

Удалить выгрузку

DELETE /api/v1/report-exports/{id}

Удаляет выгрузку в любом состоянии и освобождает место в квоте. Ответ — код 204 без тела. Ошибка: 404, код not_found.

Сохранённые отчёты

Сохранённый отчёт — название и набор настроек конструктора: то, что в панели открывается из списка сохранённых отчётов. Всем методам нужен доступ full. Объект:

Поля definition. Объект занимает не больше 32 КиБ, поле вне этого списка даёт ошибку 422:

Список сохранённых отчётов

GET /api/v1/report-views

Возвращает массив сохранённых отчётов создателя токена. Недавно изменённые идут первыми. Параметров нет.

Сохранить отчёт

POST /api/v1/report-views

Создаёт сохранённый отчёт. В теле два обязательных поля: name и definition. Ответ — код 201 и объект.

Ошибка 422 с кодом validation: неверное название, настройки больше 32 КиБ, неизвестное поле в definition, неизвестная группировка, метрика или оператор. Причина — в message.

Изменить сохранённый отчёт

PUT /api/v1/report-views/{id}

Заменяет название и настройки целиком. Тело и проверки те же, что при создании. Ответ — код 200 и объект. Ошибки: 422 с кодом validation, 404 с кодом not_found.

Удалить сохранённый отчёт

DELETE /api/v1/report-views/{id}

Ответ — код 204 без тела. Ошибка: 404, код not_found.

Свои метрики

Пользовательская метрика — колонка отчёта по формуле из встроенных метрик. Метрики общие для всей команды. Список доступен токенам reports:read и full, создание, изменение и удаление — только full. Объект:

Список своих метрик

GET /api/v1/custom-metrics

Возвращает массив метрик. Параметров нет.

Создать метрику

POST /api/v1/custom-metrics

Тело — поля объекта без id. Ответ — код 201 и объект.

Ошибка 422 с кодом validation: name и formula обязательны, имя совпадает с базовой метрикой, имя — только латиница, цифры и _ или сообщение, которое начинается с ошибка в формуле:. Разбор сообщений — в разделе Сообщения об ошибках.

Изменить метрику

PUT /api/v1/custom-metrics/{id}

Передавайте все поля: name, formula, title и decimals заменяются значениями из тела. Пустой format оставляет прежний формат. Ответ — код 200 и объект. Ошибки: 422 с кодом validation, 404 с кодом not_found.

Удалить метрику

DELETE /api/v1/custom-metrics/{id}

Ответ — код 204 без тела. Ошибка: 404, код not_found.

Клики

Три метода отдают данные по отдельным кликам. Всем нужен доступ full. Поиск клика по IP, subid или external_id и полная карточка клика описаны на странице Admin API: логи и диагностика.

Журнал кликов

GET /api/v1/reports/clicks

Возвращает последние клики по всем кампаниям за период, новые первыми.

Дата, которую не удалось разобрать, заменяется значением по умолчанию. Знак + в смещении часового пояса кодируйте как %2B или передавайте время в UTC с буквой Z.

Ответ — код 200 и объект {"items": [...]}. Поля клика: time, click_id, campaign_id, source_id, offer_id, country, city, device, os, browser, ip, is_bot, cost, external_id, sub_id_1.

Ошибки: 503 с кодом no_analytics — аналитика недоступна, 400 с кодом report_error — запрос не выполнен.

Решение клоаки по клику

GET /api/v1/reports/click-cloak?subid=<subid>

Возвращает решение клоаки по клику. Параметр запроса subid обязателен — это click_id из журнала кликов.

Ответ — код 200. Если решение по клику не сохранено, приходит {"found": false}. Иначе — {"found": true, "verdict": {...}}:

Ошибки: 400 с кодом bad_request — нет параметра subid; 404 с кодом not_found и сообщением click not found — клика нет.

Данные лида по клику

GET /api/v1/reports/click-lead?subid=<subid>

Возвращает контактные данные, которые форма лендинга привязала к клику. Параметр запроса subid обязателен.

Ответ — код 200 и объект {"found": true, "lead": {...}}. Поля lead: email, phone, first_name, last_name. Если данных по клику нет, found равно false, а поля lead пустые.

Ошибки те же, что у решения клоаки.