API статистики каналов MAX: пошаговое руководство по API.Max

API.Max — это программный доступ к данным datool.ru о каналах мессенджера MAX: каталогу и карточкам каналов, статистике по дням и постам. Через API статистику каналов MAX можно забрать в свою таблицу, BI-систему, CRM, бота или ИИ-ассистента — без ручных выгрузок и копирования с сайта. Ответы приходят в JSON, ключ один на сотрудника, а начать можно бесплатно.

В этой статье — путь от пустого ключа до рабочей интеграции: как получить ключ, найти канал, забрать статистику сразу по сотне каналов, выгрузить посты, получать новые посты сами собой через вебхуки и не потратить лишние запросы. Все примеры — на Python с библиотекой requests; полный справочник методов с примерами на curl — на docs.datool.ru/api/.

Что можно получить через API.Max

• Каталог каналов — поиск по названию, рубрикам, территории, числу подписчиков, метке A+, подтверждению владельцем, госканалам, давности последнего поста и индексу качества. Те же фильтры, что в каталоге max.datool.ru/channels/.
• Карточку канала — название, описание, имя и ссылку, подписчиков, рубрики, территорию, теги, индекс качества и индекс цитируемости, метку A+ и синий знак подтверждения.
• Статистику по дням — подписчики на конец дня, число постов, просмотры и реакции постов этого дня, рекламные посты. До 100 каналов за один запрос.
• Посты — текст, просмотры, реакции по эмодзи, признак рекламы, источник репоста и вложения. Страницами до 100 постов.
• Новые посты по событию — вебхук сам присылает их на ваш сервер.
• Справочники рубрик и территорий — бесплатно.

Чего в API нет и не будет: личных переписок, сообщений групповых чатов и комментариев — мы их не собираем. У закрытых каналов через API доступна только карточка.

Шаг 1. Получите ключ

Зарегистрируйтесь на hi.datool.ru, откройте «API-ключи» и нажмите «Создать ключ». Полный ключ вида dtk_… показывается один раз — сохраните его в настройках программы или в менеджере паролей.

Ключ принадлежит организации: её тариф, её лимит запросов и закрытые каналы, которые она подтвердила. Лимит общий — его расходуют ключи всех участников. Если участника отключить от организации, его ключи отзываются автоматически.

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

Шаг 2. Первый запрос — «Кто я»

Ключ передаётся в заголовке Authorization: Bearer dtk_… (или X-API-Key). Первым удобно вызвать /v1/me/: он бесплатный и показывает тариф, лимит и остаток запросов.

import requests

API = "https://api.datool.ru/v1"
# ключ из кабинета — храните его в настройках, не в коде
HEADERS = {"Authorization": "Bearer dtk_ваш_ключ"}

me = requests.get(f"{API}/me/", headers=HEADERS, timeout=30).json()
# тариф API, сколько запросов осталось и когда лимит обновится
print(me["api_tariff"], me["remaining_period"], me["period_end"])

Если ответ пришёл — ключ работает. Ошибка 401 означает, что ключа нет, он неверный или отозван.

Шаг 3. Найдите каналы

Все остальные методы работают с номером канала в datool.ru — полем id. Получить его можно двумя способами.

Один канал по ссылке. Метод resolve понимает ссылку max.ru/…, @имя и ID чата MAX:

channel = requests.get(
    f"{API}/max/channels/resolve/",
    params={"q": "https://max.ru/citynews"},
    headers=HEADERS,
    timeout=30,
).json()
print(channel["id"], channel["title"], channel["subscribers"])

Подборку каналов по фильтрам. Например, новостные каналы Москвы от 10 тысяч подписчиков, которые писали на этой неделе, — по убыванию индекса качества:

catalog = requests.get(
    f"{API}/max/channels/",
    params={
        "category": "news",          # код рубрики из справочника /max/categories/
        "territory": "ru-mow",       # код территории из /max/territories/
        "subscribers_min": 10000,
        "posted_within_days": 7,
        "ordering": "-quality",
        "limit": 100,
    },
    headers=HEADERS,
    timeout=30,
).json()
ids = [card["id"] for card in catalog["results"]]

Коды рубрик и территорий берите из бесплатных справочников /v1/max/categories/ и /v1/max/territories/. Территория включает своих потомков: по коду федерального округа найдутся каналы всех его регионов.

Шаг 4. Статистика по дням — до 100 каналов за запрос

Метод /v1/max/stats/daily/ отдаёт строки «канал × день»: подписчиков на конец дня, число постов, просмотры и реакции постов этого дня и число рекламных постов. За один запрос — до 100 каналов и до 366 дней, всего не больше 10 000 строк. Стоит такой запрос столько же, сколько запрос по одному каналу, — 1 единицу.

stats = requests.get(
    f"{API}/max/stats/daily/",
    params={
        "channels": ",".join(map(str, ids)),  # до 100 номеров через запятую
        "from": "2026-10-01",
        "to": "2026-10-25",
    },
    headers=HEADERS,
    timeout=30,
).json()

for row in stats["results"]:
    print(row["channel"], row["day"], row["subscribers"], row["views"], row["ad_posts"])
# номера, которых нет или которые вам не видны
print(stats["not_found"])

Дни считаются по московскому времени. Если в какой-то день канал не опрашивали, subscribers придёт как null — это «нет данных», а не ноль, и строить по такому дню падение аудитории не нужно. На бесплатном тарифе «API.Max Тест» доступны последние 30 дней, вся история — с тарифа «Старт».

Шаг 5. Посты канала

Посты отдаются страницами, новые сверху. Берите ссылку на следующую страницу из поля next целиком: курсор в ней помнит фильтры и не даёт повторов, даже если пока вы листаете, в канале выходят новые посты.

url = f"{API}/max/channels/@citynews/posts/"
params = {"from": "2026-10-01", "limit": 100}
posts = []
while url:
    page = requests.get(url, params=params, headers=HEADERS, timeout=30).json()
    posts += page["results"]
    url, params = page["next"], None  # в next уже есть все параметры
print(len(posts), "постов")

У каждого поста — текст, время публикации, просмотры, реакции по эмодзи ({"👍": 180, "🔥": 56}), признак рекламы is_ad, источник репоста и вложения. Фильтр is_ad=true вернёт только рекламные посты — удобно для анализа рекламодателей. Посты открыты с тарифа «API.Max Старт».

Шаг 6. Новые посты без опроса — вебхуки

Опрашивать ленту каждые пять минут — дорого и медленно. Вебхук сам присылает POST-запрос на ваш сервер о каждом новом посте выбранных каналов — обычно через 1–2 минуты после того, как мы его прочитали. Вебхуки открыты с тарифа «API.Max Рост» (1 вебхук до 500 каналов), на «Профи» — 5 вебхуков до 5 000 каналов каждый. Управление вебхуками запросов не тратит.

Создаёт вебхук ключ с отметкой «Чтение и запись» владельца или администратора организации:

hook = requests.post(
    f"{API}/max/webhooks/",
    json={"url": "https://example.com/hooks/datool", "channels": ids[:500]},
    headers=HEADERS,
    timeout=30,
).json()
# секрет подписи показывается один раз — сохраните его
print(hook["id"], hook["secret"])

Три правила надёжного приёмника:

• Проверяйте подпись. Каждое событие подписано: заголовок X-Datool-Signature содержит время и HMAC-SHA256. Сверяйте подпись до разбора JSON и отклоняйте события старше 5 минут. Готовая функция проверки и приёмник на Flask — в статье «Вебхуки».
• Отвечайте быстро. Код 2xx за 10 секунд, тяжёлую обработку — после ответа. Иначе мы повторим доставку: через 1, 5, 15 минут, 1, 3, 6 и 12 часов.
• Будьте готовы к повторам. Одно событие может прийти дважды — сверяйте посты по id.

Если за сутки не прошло ни одной доставки, вебхук выключается, а владельцам и администраторам приходит письмо. Почините сервер и включите вебхук кнопкой на странице «API-ключи» или запросом PATCH с {"is_active": true}.

Данные MAX в ИИ-ассистенте: MCP

Если код писать не хочется, подключите к ассистенту MCP-сервер https://api.datool.ru/v1/mcp/ с тем же ключом. Claude, Cursor и другие клиенты MCP сами найдут канал, посмотрят статистику и посты и ответят на вопрос вроде «как рос канал @citynews в октябре». Каждый вызов инструмента стоит столько же, сколько метод API. Настройка для разных клиентов — в статье «MCP для ИИ-ассистентов» и на странице hi.datool.ru/mcp/.

Как не тратить лишние запросы

Запрос стоит 1 единицу независимо от того, сколько строк он вернул. Отсюда простые правила:

• Собирайте пачками. Статистика по 100 каналам — 1 запрос, а не 100. Карточки списка каналов — каталогом с ids (до 100 номеров), а не по одной.
• Берите страницы по 100. У каталога и постов поставьте limit=100: страниц вдвое меньше, чем по умолчанию.
• Не опрашивайте ленту — подключите вебхук. Новые посты придут сами, и запросы на проверку ленты не понадобятся.
• Кешируйте справочники и номера каналов. Номер канала в datool.ru не меняется — найдите его один раз через resolve и сохраните.
• Следите за заголовками. X-Quota-Remaining — остаток за период, X-Quota-Reset — когда начнётся новый, X-RateLimit-Remaining — остаток в эту секунду.

Не тратят лимит запросы без ключа или с неверным ключом, отклонённые по лимиту (429) и не выполненные по нашей вине (500, 503).

Ошибки: как писать надёжный клиент

Ошибка приходит в виде {"detail": "текст", "code": "код"}. Решения в программе принимайте по code, а текст показывайте человеку — по заголовку Accept-Language: en он придёт по-английски.

• 429 — rate_limited (слишком часто) или quota_exceeded (запросы за период закончились). Подождите столько секунд, сколько указано в заголовке Retry-After.
• 503 — timeout (выборка слишком большая: сузьте период или число каналов) или unavailable (база временно недоступна: повторите через несколько минут). Такие запросы лимит не тратят.
• 403 — tariff_required (метод или период закрыт тарифом), closed_channel (посты закрытого канала не отдаются), read_only_key (ключ без права записи).
• 404 — канала или поста нет, или ваш ключ его не видит.

Полный список кодов — в статье «Ошибки».

Какой тариф выбрать

• API.Max Тест — бесплатно. 1 000 запросов за 30 дней, 1 запрос в секунду, карточки и статистика за последние 30 дней. Чтобы попробовать и проверить идею.
• API.Max Старт — 2 990 ₽ в месяц. 100 000 запросов, 5 в секунду, 2 ключа, вся история статистики и посты. Для своих сервисов, ботов и регулярных отчётов.
• API.Max Рост — 9 990 ₽ в месяц. 300 000 запросов, 10 в секунду, 5 ключей и вебхуки. Для продуктов с аналитикой, которым нужны новые посты сразу.
• API.Max Профи — 29 990 ₽ в месяц. 1,5 млн запросов, 20 в секунду, 20 ключей и право показывать данные своим клиентам. Для агентств и платформ.
• API.Max Корпоративный — по договору. От 5 млн запросов и выгрузка базы.

В подписку «Бизнес» уже входит 10 000 запросов в месяц. Месяц лимита — 30 дней с момента оплаты; если лимит кончился раньше, можно докупить пакет 100 000 запросов за 990 ₽. Все тарифы — на странице max.datool.ru/api/.

Частые вопросы