API к отчётам

API отчётов даёт доступ к тем же данным, что и расширенная отчётность в Google Doc или Excel — но в формате CSV, удобном для загрузки в сторонние аналитические системы (BI, дашборды, собственные скрипты).

Кратко

• Данные выгружаются по временным окнам — вы задаёте date_from и date_to в формате Unix time.
• За один запрос возвращается не более 10 000 записей, отсортированных от новых к старым.
• API доступен для Telegram и Max — отличается только базовый URL.

Как работать с API

Рекомендуемый порядок — инкрементальная выгрузка:

1. Сделайте первый запрос с нужным диапазоном дат.
2. Сохраните полученные данные.
3. Запомните максимальную дату (eventDate или date) из выгрузки.
4. В следующем запросе укажите эту дату в date_from — она войдёт в результат, дубликаты легко отфильтровать.
5. Повторяйте, пока не получите все данные.

Если за один запрос пришло ровно 10 000 записей — сдвиньте date_from и запросите следующую порцию.

подсказка

Чтобы ускорить работу, всегда указывайте date_from и ставьте в него максимальную дату из предыдущей выгрузки. Запрос без дат вернёт только последние 10 000 записей.

Формат запроса

Выберите платформу — шаблон URL отличается только путём к API:

Telegram

https://report.tgtrack.ru/api/МЕТОД__API?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Max

https://report.tgtrack.ru/max/api/МЕТОД__API?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Параметры

Параметр	Обязательный	Описание
МЕТОД__API	да	Имя метода — см. раздел Методы API ниже.
apiKey	да	Ключ для отчётов. Получить в боте: меню → ключ для отчётов.
date_from	нет	Начало периода (Unix time). По умолчанию — с момента добавления бота в канал.
date_to	нет	Конец периода (Unix time). По умолчанию — текущий момент.
limit	нет	Максимум записей в ответе. По умолчанию — 10 000.

Записи в ответе отсортированы от новых к старым.

Методы API

Ниже — четыре метода. Структура полей ответа одинакова для Telegram и Max; в каждом методе приведены готовые URL для обеих платформ.

---

get_chat_members.php — подписчики

Список подписчиков канала или бота: подписки, отписки, UTM-метки, статусы.

Telegram

https://report.tgtrack.ru/api/get_chat_members.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Max

https://report.tgtrack.ru/max/api/get_chat_members.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Поле	Описание
userID	Уникальный идентификатор пользователя.
status	Статус: 1 — подписан, 0 — отписался, -1 — бан.
joinDate	Дата подписки (unixtime).
leftDate	Дата отписки, если есть (unixtime).
inviteLinkID	ID пригласительной ссылки, через которую пришёл пользователь.
first_name	Имя.
last_name	Фамилия.
username	Никнейм в мессенджере.
tag_id	ID тега, присвоенного пользователю.
utm_source_id	UTM Source.
utm_medium_id	UTM Medium.
utm_campaign_id	UTM Campaign.
utm_content_id	UTM Content.
utm_term_id	UTM Term.
subscribersCount	Сколько подписчиков добавилось (для подписок — 1).
unsubscribersCount	Сколько подписчиков убавилось (для отписок — 1).
is_premium	Признак Telegram Premium (только Telegram).
eventDate	Дата события — подписка, отписка и т.д. (unixtime).

---

get_click_data.php — переходы и клики

Переходы в канал с лендингов и трекинг-ссылок: время визита, конверсия в подписку, данные Яндекс.Метрики.

Telegram

https://report.tgtrack.ru/api/get_click_data.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Max

https://report.tgtrack.ru/max/api/get_click_data.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Поле	Описание
ID	Уникальный ID записи о переходе.
date	Дата и время клика (unixtime).
linkID	ID ссылки, по которой был переход.
extraPath	Номер поста, на который был переход.
tag_id	ID метки, связанной с кликом.
isRedeemed	Переход конвертирован в подписку (true / false).
isSubscriber	Пользователь был подписчиком на момент события.
redeemDate	Дата засчитывания подписки (unixtime), если применимо.
tgUserID	ID пользователя в мессенджере (если известен).
yaClientID	Client ID Яндекс.Метрики.
visitDuration	Длительность визита на ленде, секунды.
utm_source_id	UTM Source.
utm_medium_id	UTM Medium.
utm_campaign_id	UTM Campaign.
utm_term_id	UTM Term.
utm_content_id	UTM Content.
yaMetrikaUploadStatus	Статус выгрузки события в Яндекс.Метрику.
yaVisitNum	Номер визита по данным Яндекс.Метрики.

---

get_tracking_links.php — справочник ссылок

Справочник источников трафика:

• инвайт-ссылки;
• интеграции с Яндекс, ФБ, ВК, Google;
• трекинг-ссылки бота.

Telegram

https://report.tgtrack.ru/api/get_tracking_links.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Max

https://report.tgtrack.ru/max/api/get_tracking_links.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ&date_from=ДАТА_НАЧАЛА&date_to=ДАТА_ОКОНЧАНИЯ&limit=МАКС_ЗАПИСЕЙ

Поле	Описание
linkID	Уникальный ID ссылки.
name	Название источника (кампания, канал и т.п.).
type	Тип: UTM, ручная ссылка, партнёр и др.
targetUrl	Целевой URL ссылки.
createdDate	Дата создания.

---

get_tags.php — справочник меток

Полный справочник тегов и UTM-меток. Параметры date_from, date_to и limit для этого метода не используются.

Telegram

https://report.tgtrack.ru/api/get_tags.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ

Max

https://report.tgtrack.ru/max/api/get_tags.php?ver=1.0&platform=api&format=csv&apiKey=ВАШ_КЛЮЧ_ДЛЯ_ОТЧЕТОВ

Поле	Описание
labelID	Уникальный ID метки.
name	Название метки.

Лимиты запросов

Лимиты действуют на каждый чат (на каждый ключ для отчётов). При превышении API вернёт ошибку Too many requests.

Интервал	Макс. запросов
1 секунда	3
1 час	500
1 день	5 000