Экспорт данных

Экспорт отдаёт сырые данные Tracehub — установки, события, клики, постбэки и затраты — в ваши системы: BI, хранилище, скрипты. Работает двумя способами: Pull API (запросы по HTTP с постраничным JSON) и файловые выгрузки (файл целиком, готовится в фоне; в кабинете — CSV).

В кабинете Tracehub: Данные → Экспорт. Три вкладки: «Экспорт данных» (конструктор запроса), «API-ключи» (токены доступа — см. страницу API-токены) и «Расписание отчётов и выгрузки».

Типы отчётов

Тип	Код	Что внутри
Установки	installs	Органические и неорганические установки с данными атрибуции
In-app события	events	Все события SDK: покупки, регистрации, произвольные
Рекламные контакты	ad_interactions	Клики из рекламных сетей
Постбэки	postbacks	Исходящие постбэки к рекламным сетям
Затраты	cost	Агрегаты затрат по дням

Один запрос — один тип отчёта.

Дополнительные параметры событий в выгрузку не попадают

Отчёт «In-app события» отдаёт стандартные поля: токен события, время, доход, валюту, данные атрибуции. Произвольные параметры, отправленные вместе с событием, в выгрузке отсутствуют — работать с ними можно только как с фильтром и разбивкой в отчётах кабинета, и только после того, как у параметра включена настройка «Индексировать».

Метка среды (тестовая или боевая) доступна в отчёте «In-app события»: колонка входит в набор полей по умолчанию. Фильтра по среде в запросе нет — отбирайте нужные строки уже в выгруженных данных.

Для разработки и тестирования заведите отдельное приложение

Создайте в кабинете второе приложение — например «MyApp Test» — и укажите его SDK-токен в отладочных сборках. Тогда данные тестирования собираются под отдельным app_id и не смешиваются с выгрузками по боевому приложению. Если к тестовому приложению подключены рекламные кабинеты, постбэки по тестовым событиям будут отправлены партнёрам — учитывайте это при настройке источников тестового приложения.

Конструктор в кабинете

Вкладка «Экспорт данных» собирает запрос по шагам: тип отчёта → период и фильтры → поля. Справа — готовый рецепт cURL (ID организации в нём уже подставлен) и предпросмотр JSON; в режиме «Экспорт файла» — кнопка выгрузки CSV со статусом задания. Начинать интеграцию удобнее всего отсюда: скопируйте cURL и подставьте свой токен.

Pull API

Синхронный HTTP-запрос, ответ — JSON с курсорной пагинацией.

GET https://api.tracehub.ru/export/{reportType}

Заголовки:

Заголовок	Значение
Authorization	Bearer tracehub_pat_… — API-токен с правом export:read (см. страницу API-токены)
X-Tenant-Id	ID организации (подставлен в cURL-рецепте кабинета)
Accept	application/json или text/csv

Параметры запроса:

Параметр	Обяз.	Описание
app_id	✓	ID приложения
date_from	✓	Начало окна, YYYY-MM-DD
date_to	✓	Конец окна, YYYY-MM-DD. Окно полуоткрытое: [date_from, date_to) — день date_to не входит
limit		Строк на страницу, 1–10 000 (по умолчанию 1000)
cursor		Курсор следующей страницы из предыдущего ответа
format		json (по умолчанию) или csv
sourceIds		Фильтр по источникам — ID подключённых кабинетов, через запятую
country		Коды стран ISO-3166 alpha-2, через запятую
platform		ios или android
event		Токены событий, через запятую (только отчёт events)
fields		Список колонок через запятую; без параметра вернутся все

Какие фильтры применимы к какому отчёту:

Отчёт	Источник	Страна	Платформа	Событие
installs	✓	✓	✓	—
events	✓	✓	✓	✓
ad_interactions	✓	—	—	—
postbacks	✓	—	—	—
cost	✓	—	—	—

Ответ:

{
  "data": [ { "...": "строки отчёта" } ],
  "nextCursor": "…",
  "total": 1000
}

total — число строк на этой странице, а не всего результата: курсорная пагинация не считает общий итог. Повторяйте запрос с cursor=nextCursor, пока он не станет null. Поле degraded: true в ответе означает, что часть данных за выбранный период временно недоступна: повторите запрос позже.

Перечень колонок каждого отчёта отдаёт отдельный запрос — он же наполняет конструктор полей в кабинете:

GET https://api.tracehub.ru/export/schema/{reportType}

Pull API — для интерактивных срезов, не для массовой перекачки

Синхронная выгрузка ограничена глубиной в 50 страниц подряд; дальше API ответит ошибкой 413 с подсказкой перейти на файловую выгрузку. Полные объёмы забирайте файловыми заданиями.

Файловые выгрузки (задания)

Отчёты installs, events, ad_interactions, postbacks выгружаются целиком асинхронным заданием: создаёте задание, ждёте готовности, скачиваете файл по ссылке.

Действие	Запрос
Создать задание	POST /export/{reportType}/jobs — тело повторяет фильтры Pull API, плюс format: csv, jsonl или parquet (по умолчанию parquet). Ответ 202 с jobId
Статус задания	GET /export/jobs/{id} — статусы queued → running → ready (или failed / canceled; готовый файл со временем переходит в expired)
Список заданий	GET /export/jobs
Отменить	DELETE /export/jobs/{id}

Когда задание в статусе ready, в ответе появляется downloadUrl — подписанная ссылка на файл, действующая до expiresAt (после этого файл и ссылка удаляются). Для регулярной дозагрузки только новых строк передайте since — водяной знак из поля nextWatermark предыдущего запуска: выгрузятся только строки новее него.

Отчёт cost файловых заданий не имеет — CSV по затратам отдаётся синхронно тем же GET /export/cost?format=csv (в кабинете кнопка «Экспортировать файл» делает это сама).

В кабинете файловая выгрузка запускается из режима «Экспорт файла» (формат — CSV); статус и история всех заданий — на вкладке «Расписание отчётов и выгрузки». Число одновременно активных заданий ограничено — при превышении API отвечает 429.

Расписания выгрузок

Регулярные отчёты настраиваются на вкладке «Расписание отчётов и выгрузки»: любой сохранённый отчёт из раздела «Отчёты» можно поставить на расписание — ежедневно, еженедельно или ежемесячно — и он будет приходить на указанные адреса электронной почты в виде CSV. Расписание можно приостановить, возобновить или удалить; на карточке видны последняя отправка и следующий запуск.

Лимиты

Ограничение	Значение
Окно одного запроса или задания	до 31 дня (большие периоды — по месяцу за запрос)
Строк на страницу (Pull API)	до 10 000
Страниц синхронно	до 50, дальше — файловая выгрузка
Запросов на API-токен	100 в час (по умолчанию)

---