# MAX Channel Statistics API: step-by-step guide to the API.MAX > How to get MAX channel statistics via the API.MAX: key, channel search, statistics on 100 channels per request, posts, webhooks about new posts, MCP, saving requests, errors and tariff selection — with examples in Python. Articles · 2026-11-03 · Евгений Химич · https://hi.datool.ru/en/notes/max-channel-statistics-api/ API.MAX is a programmatic access to data datool.ru about MAX messenger channels: catalog and channel cards, statistics on days and posts. Through the API, MAX channel statistics can be collected in your table, BI-system, CRM, bot or AI assistant - without manual uploads and copying from the site. Responses are sent in JSON, one key per employee, and you can start for free. In this article — the path from an empty key to a working integration: how to get a key, find a channel, pick up statistics on hundreds of channels at once, upload posts, get new posts by themselves through webhooks and not spend extra requests. All examples are in Python with the requests library; a complete guide to methods with examples in curl is in [docs.datool.ru/api /](https://docs.datool.ru/api/). ## What can be accessed via the API.MAX - **Channel catalog** — search by name, categories, territory, number of subscribers, A+ tag, confirmation by the owner, state channels, the statute of limitations of the last post and the Quality index. The same filters as in the catalog [max.datool.ru/channels /](https://max.datool.ru/channels/). - **Channel card** — name, description, name and link, subscribers, categories, territory, tags, Quality index and Citation index, A+ label and a blue confirmation sign. - **Statistics by day** — subscribers at the end of the day, the number of posts, views and reactions of posts of that day, advertising posts. Up to 100 channels per request. - **Posts** — text, views, emoji reactions, ad feature, repost source, and attachments. Pages of up to 100 posts. - **New posts on the event** — the webhook itself sends them to your server. - **Directories** of categories and territories are free of charge. What the API doesn't and won't do: personal correspondence, group chat messages, and comments — we don't collect them. For closed channels, only the card is available via the API. ## Step 1. Get the key Register on hi.datool.ru . open "API Keys" and click "Create Key". The full key of type `dtk_…` is shown once — save it in the program settings or in the password manager. The key belongs to the organization: its pricing plan, its request limit, and closed channels that it has confirmed. The limit is general — it is spent by the keys of all participants. If a participant is disconnected from the organization, their keys are revoked automatically. When creating a key, you can mark "Read and write". It is only needed to manage webhooks; a regular key is enough to read the data. You can't change the mark later, so it's convenient to have a separate key for webhooks. !!! warning "Important" Do not publish the key in the repository and do not insert it into the site page scripts: they can use up your organization's limit. ## Step 2. The first query is "Who am I" The key is passed in header `Authorization: Bearer dtk_…` (or `X-API-Key`). It is convenient to call `/v1/me/` first: it is free and shows the tariff, limit and balance of requests. ```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"]) ``` If the response is received, the key works. A 401 error means that the key is missing, invalid, or revoked. ## Step 3. Find channels All other methods work with the channel number in datool.ru — field `id`. You can get it in two ways. **One channel by link.** Method `resolve` understands link `max.ru/…`, `@имя` and chat 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"]) ``` **A Collection of channels by filters.** For example, news channels in Moscow from 10 thousand subscribers who wrote this week — in descending order of the Quality index: ```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"]] ``` Get the codes of categories and territories from the free directories `/v1/max/categories/` and `/v1/max/territories/`. The territory includes its descendants: according to the code of the federal district, there are channels of all its regions. ## Step 4. Statistics by day — up to 100 channels per request Method `/v1/max/stats/daily/` returns the lines "channel × day": subscribers at the end of the day, the number of posts, views and reactions of posts of that day, and the number of advertising posts. For one request — up to 100 channels and up to 366 days, no more than 10,000 lines in total. Such a request costs the same amount as a request for one channel — 1 unit. ```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"]) ``` Days are counted according to Moscow time. If the channel was not polled on some day, `subscribers` will come as `null` - this is "no data", not zero, and there is no need to build a drop in the audience on such a day. On the free tariff "API.MAX Test" the last 30 days are available, the whole story is from the "Start" tariff. ## Step 5. Channel Posts Posts are given pages, new ones on top. Take the link to the next page from field `next` in its entirety: the cursor in it remembers the filters and does not give repetitions, even if while you are scrolling, new posts are coming out in the channel. ```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), "постов") ``` Each post has a text, publication time, views, emoji reactions (`{"👍": 180, "🔥": 56}`), `is_ad` advertising signs, a repost source and attachments. Filter `is_ad=true` will return only advertising posts — convenient for analyzing advertisers. Posts are opened with the "API.MAX Start". ## Step 6. New posts without a survey — webhooks Polling the feed every five minutes is expensive and slow. The webhook itself sends a POST request to your server about each new post of the selected channels - usually 1-2 minutes after we read it. Webhooks are open with the "API.MAX Growth" (1 webhook up to 500 channels), on "Pros" — 5 webhooks up to 5,000 channels each. Webhook management does not waste requests. Creates a webhook key marked "Read and write" by the owner or administrator of the organization: ```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"]) ``` Three rules of a reliable receiver: - **Check the signature.** Each event is signed: header `X-Datool-Signature` contains the time and HMAC-SHA256. Verify the signature before parsing the JSON and reject events older than 5 minutes. The ready—made verification function and receiver on Flask are in the article ["Webhooks"](https://docs.datool.ru/api/webhooks/). - **Answer quickly.** Code 2xx in 10 seconds, heavy processing — after the response. Otherwise, we will repeat the delivery: in 1, 5, 15 minutes, 1, 3, 6 and 12 hours. - **Be prepared for repetitions.** One event can come twice — check the posts by `id`. If no delivery has been made in a day, the webhook is turned off, and an email is sent to the owners and administrators. Fix the server and enable the webhook by clicking on the "API keys" page or by requesting `PATCH` from `{"is_active": true}`. ## MAX data in the AI assistant: MCP If you don't want to write the code, connect MCP server `https://api.datool.ru/v1/mcp/` with the same key to the assistant. Claude, Cursor and other MCP clients will find the channel themselves, look at statistics and posts and answer a question like "how did the @citynews channel grow in October". Each call to the tool costs the same as the API method. Settings for different clients can be found in the article ["MCP for AI assistants"](https://docs.datool.ru/api/mcp/) and on the page [hi.datool.ru/mcp /](https://hi.datool.ru/mcp/). ## How not to waste extra requests A query costs 1 unit regardless of how many rows it returned. Hence the simple rules: - **Collect in packs.** Statistics for 100 channels is 1 request, not 100. Channel list cards are a catalog with `ids` (up to 100 numbers), not one at a time. - **Take pages of 100.** Set the catalog and posts to `limit=100`: there are half as many pages as by default. - **Don't poll the feed — connect the webhook.** New posts will arrive by themselves, and requests for checking the feed will not be needed. - **Cache directories and channel numbers.** Channel number in datool.ru does not change — find it once after `resolve` and save it. - **Follow the headlines.** `X-Quota-Remaining` is the remainder for the period, `X-Quota-Reset` is when the new one starts, `X-RateLimit-Remaining` is the remainder at this second. Requests without a key or with an incorrect key that are rejected by the limit (429) and not executed due to our fault (500, 503) do not spend the limit. ## Errors: how to write a reliable client The error comes in the form of `{"detail": "текст", "code": "код"}`. Make decisions in the program by `code`, and show the text to the person — by heading `Accept-Language: en` it will come in English. - **429** — `rate_limited` (too often) or `quota_exceeded` (requests for the period ended). Wait as many seconds as indicated in heading `Retry-After`. - **503** — `timeout` (the sample is too large: narrow down the period or number of channels) or `unavailable` (the base is temporarily unavailable: repeat after a few minutes). Such requests do not spend the limit. - **403** — `tariff_required` (the method or period is closed by the tariff), `closed_channel` (closed channel posts are not given), `read_only_key` (key without the right to record). - **There is no 404** channel or post, or your key does not see it. The full list of codes is in the article ["Errors"](https://docs.datool.ru/api/errors/). ## Which tariff to choose - **API.MAX Test is free.** 1,000 requests in 30 days, 1 request per second, cards and statistics for the last 30 days. To try and test the idea. - **API.MAX Start — 2,990 rubles per month.** 100,000 requests, 5 per second, 2 keys, the entire history of statistics and posts. For their services, bots and regular reports. - **API.MAX Growth — 9,990 rubles per month.** 300,000 requests, 10 per second, 5 keys and webhooks. For products with analytics that need new posts right away. - **API.MAX Pro — 29,990 rubles per month.** 1.5 million requests, 20 per second, 20 keys and the right to show data to your customers. For agencies and platforms. - **API.MAX Corporate — by agreement.** From 5 million requests and database upload. The Business subscription already includes 10,000 requests per month. The limit month is 30 days from the date of payment. If the limit ends earlier, you can purchase a package of 100,000 requests for 990 rubles. All rates are on the page [max.datool.ru/api /](https://max.datool.ru/api/). ## Frequent questions ### Is it possible to get statistics of any MAX channel via the API? Any open channel that is in the catalog datool.ru : card, daily statistics, and posts. For a closed channel, only the card is available via the API. If the channel you need is not in the catalog, you can add it to [max.datool.ru/channels/add /](https://max.datool.ru/channels/add/). ### How often is the API data updated? The same as on the site: the API returns the same data that is visible on the feed pages. How often channels of different sizes are polled is described in the documentation article "Where the data comes from and how often it is updated". ### How much does it cost to upload the entire history of channel posts? One request for every 100 posts. A channel with 5,000 posts — 50 requests. On the "Start" tariff with a limit of 100,000 requests, this is a drop per month. ### Can I show API data to my clients? Yes, from the "API.MAX Pro" — it includes the right to show data to customers. On other tariffs, the data is for your own work. ### Is there a ready-made library for the API? There is no separate library, but there is an OpenAPI scheme: `https://api.datool.ru/v1/schema/`. From it, the generator will assemble the client in any language, and Postman will import all the methods. You can try queries without code in Swagger — link on the [methods reference](https://docs.datool.ru/api/methods/) page. API.MAX is open: create a free key in the cabinet and start with the article ["Quick start"](https://docs.datool.ru/api/start/) — the first request will take a couple of minutes.