Channels

Channel catalog

Catalog of active MAX channels (or group chats with kind=chat) filtered by title, category, territory, subscriber count, the A+ mark and owner verification. Always sorted in descending order: subscribers (default), quality index, citation index or last post time. Pages of up to 100 cards; the next page link is in the next field (null — no more pages).

With the ids parameter (up to 100 comma-separated numbers) you get the cards of those channels in request order: other filters and pagination don’t apply, invisible and unknown numbers are skipped. Private channels are visible only to the organization they are open to.

Parameters

Name	Where	Description
a_plus yes / no	query	Only with the A+ mark (true) or without it (false)
category string	query	Category code (primary or additional) from /v1/max/categories/
cursor string	query	Next page cursor — use the ready link from the next field
ids string	query	Up to 100 comma-separated channel IDs — cards in the same order, without filters or pages
kind string	query	channel — channels (default), chat — group chats Values: channel, chat
limit number	query	Rows per page: 1–100, 50 by default
ordering string	query	Ordering, always descending Values: -citation, -last_post_at, -quality, -subscribers
q string	query	Search: part of the title or handle (3+ characters), a max.ru/… link or @handle
subscribers_max number	query	Subscribers at most
subscribers_min number	query	Subscribers at least
territory string	query	Territory code from /v1/max/territories/ — including its descendants
verified yes / no	query	Only owner-verified (true) or not (false)

Response fields

Field	Type	Description
results	list	Channel cards on this page
results[].id	number	datool.ru channel number — use it to request statistics and posts
results[].external_id	number or null	Chat ID in MAX (signed, as in MAX)
results[].handle	string	Public handle without @, or empty
results[].link	string	Channel link in MAX (max.ru/…) or an empty string
results[].kind	string	channel — a channel, chat — a group chat
results[].status	string	Catalog state: active — shown; new — not checked yet; unavailable — MAX answers “not found”; removed — removed from the datool.ru catalog (posts of such channels are not returned)
results[].title	string	Channel title in MAX
results[].description	string	Channel description from MAX (may be empty)
results[].avatar_url	string or null	Avatar — our copy via the media.datool.ru CDN, or null
results[].subscribers	number or null	Subscribers (members for a chat) as of the last poll
results[].posts_total	number or null	Messages in MAX as of the last poll
results[].is_public	yes / no	Public channel (true) or private, invite-only (false); for a private one the API returns only the card
results[].a_plus	yes / no	A+ mark from MAX (Roskomnadzor registry)
results[].verified	yes / no	The owner verified the channel via the datool.ru bot
results[].category	string or null	Primary category code or null
results[].categories	list	All channel categories (up to 5)
results[].territory	object or null	Channel territory or null
results[].tags	list	Channel tags
results[].quality	number or null	Quality index 0–100 or null
results[].citation	number or null	Citation index or null
results[].adult	yes / no	The categories include “Adults only (18+)”
results[].last_post_at	date and time or null	Last post time (ISO 8601, Moscow time, +03:00)
results[].first_seen_at	date and time	When datool.ru found the channel (ISO 8601, Moscow time)
results[].updated_at	date and time	When the card was last updated (ISO 8601, Moscow time)
results[].page_url	string	Channel page on max.datool.ru
next	string or null	Next page URL or null

Errors

Code	code	When
400	field errors	An invalid parameter or body field: the error comes under the field name, for example {"channels": ["Comma-separated channel numbers."]}.
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
429	rate_limited / quota_exceeded / throttled	Too often (more requests per second than your plan allows) or the requests for the period have run out; how long to wait is in the Retry-After header.
503	timeout	The database query took longer than 5 seconds — retry later or narrow the selection.

Channel card by ID or handle

Card of a channel or group chat by datool.ru number or public handle (with or without @): title, description, subscribers, categories, territory, tags, quality and citation indexes, the A+ and owner verification marks. A private channel is visible only to the organization it is open to (it verified ownership or added it by invite); others get 404.

Parameters

Name	Where	Description
channel required string	path	Channel ID in datool.ru or public handle (with or without @)

Response fields

Field	Type	Description
id	number	datool.ru channel number — use it to request statistics and posts
external_id	number or null	Chat ID in MAX (signed, as in MAX)
handle	string	Public handle without @, or empty
link	string	Channel link in MAX (max.ru/…) or an empty string
kind	string	channel — a channel, chat — a group chat
status	string	Catalog state: active — shown; new — not checked yet; unavailable — MAX answers “not found”; removed — removed from the datool.ru catalog (posts of such channels are not returned)
title	string	Channel title in MAX
description	string	Channel description from MAX (may be empty)
avatar_url	string or null	Avatar — our copy via the media.datool.ru CDN, or null
subscribers	number or null	Subscribers (members for a chat) as of the last poll
posts_total	number or null	Messages in MAX as of the last poll
is_public	yes / no	Public channel (true) or private, invite-only (false); for a private one the API returns only the card
a_plus	yes / no	A+ mark from MAX (Roskomnadzor registry)
verified	yes / no	The owner verified the channel via the datool.ru bot
category	string or null	Primary category code or null
categories	list	All channel categories (up to 5)
categories[].id	number	Category number in the directory
categories[].slug	string	Category code (as in ?category=)
categories[].name	string	Category name
categories[].is_primary	yes / no	The channel's primary category
territory	object or null	Channel territory or null
territory.id	number	Node number in the territory directory
territory.slug	string	Territory code (as in ?territory=)
territory.name	string	Territory name
territory.kind	string	country, district, region or city
territory.path	string	Node codes from the country down to this node, separated by “/”
tags	list	Channel tags
quality	number or null	Quality index 0–100 or null
citation	number or null	Citation index or null
adult	yes / no	The categories include “Adults only (18+)”
last_post_at	date and time or null	Last post time (ISO 8601, Moscow time, +03:00)
first_seen_at	date and time	When datool.ru found the channel (ISO 8601, Moscow time)
updated_at	date and time	When the card was last updated (ISO 8601, Moscow time)
page_url	string	Channel page on max.datool.ru

Errors

Code	code	When
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
404	not_found	There is no object with this number or name, or you can’t see it.
429	rate_limited / quota_exceeded / throttled	Too often (more requests per second than your plan allows) or the requests for the period have run out; how long to wait is in the Retry-After header.
503	timeout	The database query took longer than 5 seconds — retry later or narrow the selection.

Find a channel by link or MAX ID

Find a channel by what you know: a max.ru/… link, a max.ru/join/… invite link, a @handle or the MAX chat ID (a negative number). The response is the channel card; the datool.ru number is in the id field — use it to request statistics and posts. A channel missing from our database — 404.

Parameters

Name	Where	Description
q required string	query	A max.ru/… link (including an invite link), @handle or MAX chat ID (with or without the sign)

Response fields

Field	Type	Description
id	number	datool.ru channel number — use it to request statistics and posts
external_id	number or null	Chat ID in MAX (signed, as in MAX)
handle	string	Public handle without @, or empty
link	string	Channel link in MAX (max.ru/…) or an empty string
kind	string	channel — a channel, chat — a group chat
status	string	Catalog state: active — shown; new — not checked yet; unavailable — MAX answers “not found”; removed — removed from the datool.ru catalog (posts of such channels are not returned)
title	string	Channel title in MAX
description	string	Channel description from MAX (may be empty)
avatar_url	string or null	Avatar — our copy via the media.datool.ru CDN, or null
subscribers	number or null	Subscribers (members for a chat) as of the last poll
posts_total	number or null	Messages in MAX as of the last poll
is_public	yes / no	Public channel (true) or private, invite-only (false); for a private one the API returns only the card
a_plus	yes / no	A+ mark from MAX (Roskomnadzor registry)
verified	yes / no	The owner verified the channel via the datool.ru bot
category	string or null	Primary category code or null
categories	list	All channel categories (up to 5)
categories[].id	number	Category number in the directory
categories[].slug	string	Category code (as in ?category=)
categories[].name	string	Category name
categories[].is_primary	yes / no	The channel's primary category
territory	object or null	Channel territory or null
territory.id	number	Node number in the territory directory
territory.slug	string	Territory code (as in ?territory=)
territory.name	string	Territory name
territory.kind	string	country, district, region or city
territory.path	string	Node codes from the country down to this node, separated by “/”
tags	list	Channel tags
quality	number or null	Quality index 0–100 or null
citation	number or null	Citation index or null
adult	yes / no	The categories include “Adults only (18+)”
last_post_at	date and time or null	Last post time (ISO 8601, Moscow time, +03:00)
first_seen_at	date and time	When datool.ru found the channel (ISO 8601, Moscow time)
updated_at	date and time	When the card was last updated (ISO 8601, Moscow time)
page_url	string	Channel page on max.datool.ru

Errors

Code	code	When
400	field errors	An invalid parameter or body field: the error comes under the field name, for example {"channels": ["Comma-separated channel numbers."]}.
401	not_authenticated / authentication_failed	No key, the key is wrong or revoked, the member is suspended or the key’s organization is archived.
429	rate_limited / quota_exceeded / throttled	Too often (more requests per second than your plan allows) or the requests for the period have run out; how long to wait is in the Retry-After header.
503	timeout	The database query took longer than 5 seconds — retry later or narrow the selection.