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

> Как забрать статистику каналов MAX через API.Max: ключ, поиск каналов, статистика по 100 каналам за запрос, посты, вебхуки о новых постах, MCP, экономия запросов, ошибки и выбор тарифа — с примерами на Python.

Статьи · 2026-11-03 · Евгений Химич · https://hi.datool.ru/notes/max-channel-statistics-api/

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

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

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

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

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

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

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

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

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

!!! warning "Важно"
    Не публикуйте ключ в репозитории и не вставляйте его в скрипты страниц сайта: им можно израсходовать лимит вашей организации.

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

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

```python
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:

```python
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 тысяч подписчиков, которые писали на этой неделе, — по убыванию индекса качества:

```python
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 единицу.

```python
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` целиком: курсор в ней помнит фильтры и не даёт повторов, даже если пока вы листаете, в канале выходят новые посты.

```python
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 каналов каждый. Управление вебхуками запросов не тратит.

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

```python
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 — в статье [«Вебхуки»](https://docs.datool.ru/api/webhooks/).
- **Отвечайте быстро.** Код 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 для ИИ-ассистентов»](https://docs.datool.ru/api/mcp/) и на странице [hi.datool.ru/mcp/](https://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** — канала или поста нет, или ваш ключ его не видит.

Полный список кодов — в статье [«Ошибки»](https://docs.datool.ru/api/errors/).

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

- **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/](https://max.datool.ru/api/).

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

### Можно ли получить через API статистику любого канала MAX?

Любого открытого канала, который есть в каталоге datool.ru: карточку, статистику по дням и посты. У закрытого канала через API доступна только карточка. Если нужного канала в каталоге нет, его можно добавить на [max.datool.ru/channels/add/](https://max.datool.ru/channels/add/).

### Как часто обновляются данные в API?

Так же, как на сайте: API отдаёт те же данные, что видны на страницах каналов. Как часто опрашиваются каналы разного размера, описано в статье документации «Откуда данные и как часто обновляются».

### Сколько стоит выгрузить всю историю постов канала?

По одному запросу на каждые 100 постов. Канал с 5 000 постов — 50 запросов. На тарифе «Старт» с лимитом 100 000 запросов это капля в месяц.

### Можно ли показывать данные API своим клиентам?

Да, с тарифа «API.Max Профи» — в него входит право показывать данные клиентам. На остальных тарифах данные — для собственной работы.

### Есть ли готовая библиотека для API?

Отдельной библиотеки нет, но есть схема OpenAPI: `https://api.datool.ru/v1/schema/`. Из неё генератор соберёт клиент на любом языке, а Postman импортирует все методы. Попробовать запросы без кода можно в Swagger — ссылка на странице [справочника методов](https://docs.datool.ru/api/methods/).

API.Max открыт: создайте бесплатный ключ в кабинете и начните со статьи [«Быстрый старт»](https://docs.datool.ru/api/start/) — первый запрос займёт пару минут.