Работа со статистикой

🆕 Новый эндпоинт (рекомендуется)

POST /api/v1/stats/page

Пример использования:

https://client.adstat.pro/api/v1/stats/page

Параметры запроса:

Заголовки HTTP:

В заголовках HTTP запроса необходимо передать <access_token> в формате:

• Authorization: "Bearer <access_token>"

Тело запроса:

В теле HTTP запроса передаются параметры для получения статистики.

Параметр	Тип	Описание	Обязательный
period_from	string	Начальная дата периода для получения статистики (ISO 8601)	Да
period_to	string	Конечная дата периода для получения статистики (ISO 8601)	Да
period_grouping_unit	string	Единица группировки по времени. Возможные значения: "day", "week", "month", "year", "hour", "30_minutes", "5_minutes"	Да
grouping	string[]	Группировка данных по сущностям. Возможные значения: "cabinet", "ad_object", "ad", "campaign"	Нет
platform_cabinet_ids	string[]	Фильтр по ID кабинетов платформы	Нет
ad_objects	string[]	Фильтр по объектам рекламирования	Нет
currency_code	string	Валюта для отображения финансовых показателей. По умолчанию: EUR. Доступные значения: EUR, TON, USD, RUB, USDT, STAR	Нет
order_by	string	Параметр сортировки результатов. "period" - по возрастанию даты, "-period" - по убыванию даты	Нет
limit	number	Максимальное количество записей в ответе (максимум: 500)	Нет
cursor	string	Токен пагинации для получения следующей страницы результатов	Нет

Ограничения для детальной группировки по времени

При использовании значений period_grouping_unit: "hour", "30_minutes", "5_minutes" действуют следующие ограничения:

• Доступность данных: доступны данные только за последние 5 дней
• Максимальный период запроса: период между period_from и period_to не может превышать 2 дня

Пример запроса:

POST https://client.adstat.pro/api/v1/stats/page
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "period_from": "2024-06-07T00:00:00.000Z",
  "period_to": "2024-06-07T23:59:59.000Z",
  "period_grouping_unit": "day",
  "grouping": ["cabinet", "ad"],
  "currency_code": "EUR",
  "limit": 100
}

Пример успешного ответа:

Раскрыть для просмотра ответа

{
	"columns": [
		{
			"key": "period_date",
			"type": "datetime"
		},
		{
			"key": "original_spent",
			"type": "money"
		},
		{
			"key": "original_currency",
			"type": "string"
		},
		{
			"key": "exchanged_spent",
			"type": "money"
		},
		{
			"key": "exchange_currency",
			"type": "string"
		},
		{
			"key": "views",
			"type": "number"
		},
		{
			"key": "clicks",
			"type": "number"
		},
		{
			"key": "actions",
			"type": "number"
		},
		{
			"key": "video_opens",
			"type": "number"
		},
		{
			"key": "ctr",
			"type": "number"
		},
		{
			"key": "cpc",
			"type": "number"
		},
		{
			"key": "cpm",
			"type": "number"
		},
		{
			"key": "cpa",
			"type": "number"
		},
		{
			"key": "cvr",
			"type": "number"
		},
		{
			"key": "campaign_id",
			"type": "number"
		},
		{
			"key": "platform_id",
			"type": "number"
		},
		{
			"key": "ad_object",
			"type": "string"
		},
		{
			"key": "ad_id",
			"type": "number"
		},
		{
			"key": "platform_ad_id",
			"type": "number"
		},
		{
			"key": "platform_cabinet_id",
			"type": "string"
		},
		{
			"key": "ad_title",
			"type": "string"
		},
		{
			"key": "ad_text",
			"type": "string"
		},
		{
			"key": "ad_status",
			"type": "string"
		},
		{
			"key": "ad_cpm",
			"type": "money"
		},
		{
			"key": "ad_budget",
			"type": "money"
		},
		{
			"key": "promote_url",
			"type": "string"
		},
		{
			"key": "target_type",
			"type": "string"
		},
		{
			"key": "website_name",
			"type": "string"
		},
		{
			"key": "media_type",
			"type": "string"
		},
		{
			"key": "views_limit_per_user",
			"type": "number"
		},
		{
			"key": "website_button_type",
			"type": "string"
		},
		{
			"key": "action_type",
			"type": "string"
		},
		{
			"key": "exclude_crypto",
			"type": "boolean"
		},
		{
			"key": "only_crypto",
			"type": "boolean"
		},
		{
			"key": "target_langs",
			"type": "array"
		},
		{
			"key": "additional_information",
			"type": "string"
		},
		{
			"key": "target_countries",
			"type": "array"
		},
		{
			"key": "target_locations",
			"type": "array"
		},
		{
			"key": "target_channels",
			"type": "array"
		},
		{
			"key": "target_user_channels",
			"type": "array"
		},
		{
			"key": "target_topics",
			"type": "array"
		},
		{
			"key": "target_search",
			"type": "array"
		},
		{
			"key": "target_bots",
			"type": "array"
		},
		{
			"key": "platform_cabinet_name",
			"type": "string"
		},
		{
			"key": "campaign_name",
			"type": "string"
		}
	],
	"rows": [
		{
			"period_date": "2025-11-27T14:45:00Z",
			"original_spent": "0.054000",
			"original_currency": "EUR",
			"exchanged_spent": "0.054000",
			"exchange_currency": "EUR",
			"views": 157,
			"clicks": 12,
			"actions": 3,
			"video_opens": 0,
			"ctr": "0.0",
			"cpc": "0E-10",
			"cpm": "3.0000000000",
			"cpa": "0E-10",
			"cvr": "0.0",
			"campaign_id": 10101,
			"platform_id": 10,
			"ad_object": "t.me/cute_cats_bot?start=cats123",
			"ad_id": 5669137,
			"platform_ad_id": 891,
			"platform_cabinet_id": "ACC00101",
			"ad_status": "active",
			"ad_cpm": "3.0000000000",
			"ad_budget": "4.0400000000",
			"ad_title": "🐱 Милые котики каждый день!",
			"ad_text": "😻 Получайте фото самых милых котиков прямо в Telegram!",
			"promote_url": "t.me/aboutstoloto/8702",
			"website_name": "",
			"views_limit_per_user": 3,
			"website_button_type": "",
			"action_type": "join",
			"exclude_crypto": false,
			"only_crypto": false,
			"additional_information": "erid: 1A1aa5sdAS2",
			"media_type": "",
			"platform_cabinet_name": "Cats_Lovers_Studio",
			"campaign_name": "Default",
			"target_type": "target_users",
			"target_langs": [],
			"target_countries": [],
			"target_locations": [],
			"target_channels": [],
			"target_user_channels": [],
			"target_topics": ["Pets & Animals", "Lifestyle", "Entertainment"],
			"target_search": [],
			"target_bots": []
		}
	],
	"count": 50,
	"cursor": "eyJmaadasdw12312F9mcm9tIjoiMjAyNS0wNC0zMFQyMzowMDowMFoiLCJwZXJpb2RfdG8iOiIyMDI1LTA4LTMxVDIyOjU5OjU5WiIsInBsYXRmb3JtX2NhYmluZXRfaWRzIjpbXSwiYWRfb2JqZWN0cyI6W10sInBhcnRuZXJfaWRzIjpbMTA5NTZdLCJjdXJyVyIjpbInBlcmlvZCJdLCJtYXJrIjp7InBlcmlvZF9ncm91cGluZ191bml0IjoibW9udGgiLCJncm91cGluZyI6WyJhZCJdLCJsaW1pdCI6NTAsInBvaW50ZXIiOnsicGVyaW9kX2RhdGUiOiIyMDI1LTA3LTAxVDAwOjAwOjAwIiwicGxhdGZvcm1fY2FiaW5ldF9pZCI6IkFDQzAxNjA5IiwiYWRfb2JqZWN0IjoidC5tZS9vc3RyZWUiLCJhZF9pZCI6NDE3ODExMCwiY2FtcGFpZ25faWQiOjE3Nn19fQ=="
}

Структура ответа:

Поле	Тип	Описание
columns	object[]	Метаданные колонок таблицы (см. структуру ниже)
rows	object[]	Массив строк с данными статистики (см. поля ниже)
count	number	Общее количество записей в результате
cursor	string | null	Токен пагинации для получения следующей страницы (base64 JSON или null для последней страницы)

Структура колонок (columns):

Поле	Тип	Описание
key	string	Идентификатор поля в данных
type	string	Тип данных поля: "string", "number", "money", "date", "datetime", "boolean", "array"

Поля данных в строках (rows):

В таблице ниже перечислены все возможные поля, которые могут присутствовать в строках результата в зависимости от параметров запроса:

Поле	Тип	Описание	Название на фронте
period_date	string	Дата периода (ISO 8601)	День/Неделя/Месяц/Год/Период
original_spent	string	Потраченная сумма в оригинальной валюте	-
original_currency	string	Оригинальная валюта	-
exchanged_spent	string	Потраченная сумма в валюте отчета	Расходы
exchange_currency	string	Валюта отчета	-
views	number	Количество показов	Показы
clicks	number	Количество кликов	Клики
actions	number	Количество действий	Действия
video_opens	number	Количество открытий видео	Открытия видео
ctr	string	Коэффициент кликабельности (в процентах)	CTR,% (Коэффициент кликабельности: (Клики/Показы)*100)
cpc	string	Стоимость за клик	CPC (Цена клика: Расходы/Клики)
cpm	string	Стоимость за 1000 показов (фактическая)	CPM (Стоимость за 1000 показов)
cpa	string	Стоимость за действие	CPA (Цена цели: Расход/Действия)
cvr	string	Коэффициент конверсии (в процентах)	CVR,% (Коэффициент конверсии: (Действия/Клики)*100)
campaign_id	number	ID кампании	-
platform_id	number	ID платформы	-
ad_object	string	Объект рекламирования	Объект
ad_id	number	ID объявления	-
platform_ad_id	number	ID объявления на платформе	-
platform_cabinet_id	string	ID кабинета на платформе	-
ad_status	string	Статус объявления	-
ad_cpm	string	Стоимость за 1000 показов (указанная в объявлении)	-
ad_budget	string	Бюджет объявления	-
ad_title	string | null	Название объявления	Наименование объявления
ad_text	string | null	Текст объявления	Текст креатива
promote_url	string | null	URL рекламируемого объекта	URL
website_name	string | null	Название веб-сайта	Название сайта
website_button_type	string | null	Тип кнопки веб-сайта	Текст кнопки
views_limit_per_user	number	Лимит показов на пользователя	Частота показов
action_type	string | null	Тип действия	Тип действия
exclude_crypto	boolean	Исключить криптовалютные объявления	-
only_crypto	boolean	Только криптовалютные объявления	-
additional_information	string | null	Дополнительная информация (erid токен)	-
media_type	string | null	Тип медиа	Тип медиа
platform_cabinet_name	string | null	Название кабинета на платформе	Кабинет
campaign_name	string | null	Название кампании	Название кампании
target_type	string | null	Тип таргетинга	Тип таргетинга
target_langs	string[]	Целевые языки	-
target_countries	string[] | null	Целевые страны	-
target_locations	string[] | null	Целевые локации	-
target_channels	string[] | null	Целевые каналы	-
target_user_channels	string[]	Целевые каналы пользователей	-
target_topics	string[] | null	Целевые тематики	Интересы
target_search	string[] | null	Целевые поисковые запросы	-
target_bots	string[] | null	Целевые боты	-

Доступность полей в зависимости от группировки:

В таблице ниже указано, какие поля возвращаются в ответе API в зависимости от значения параметра grouping:

Поле API	Без разбивки	По кабинетам (["cabinet"])	По кампаниям (["campaign"])	По объектам (["ad_object"])	По объявлениям (["ad"])
period_date	✓	✓	✓	✓	✓
platform_cabinet_name	✗	✓	✓	✗	✗
campaign_name	✗	✗	✓	✗	✗
ad_object	✗	✗	✗	✓	✗
ad_title	✗	✗	✗	✗	✓
ad_text	✗	✗	✗	✗	✓
promote_url	✗	✗	✗	✗	✓
website_name	✗	✗	✗	✗	✓
media_type	✗	✗	✗	✗	✓
target_type	✗	✗	✗	✗	✓
target_topics	✗	✗	✗	✗	✓
views_limit_per_user	✗	✗	✗	✗	✓
website_button_type	✗	✗	✗	✗	✓
action_type	✗	✗	✗	✗	✓
original_spent	✓	✓	✓	✓	✓
original_currency	✓	✓	✓	✓	✓
exchanged_spent	✓	✓	✓	✓	✓
exchange_currency	✓	✓	✓	✓	✓
views	✓	✓	✓	✓	✓
clicks	✓	✓	✓	✓	✓
video_opens	✓	✓	✓	✓	✓
actions	✓	✓	✓	✓	✓
ctr	✓	✓	✓	✓	✓
cvr	✓	✓	✓	✓	✓
cpm	✓	✓	✓	✓	✓
cpc	✓	✓	✓	✓	✓
cpa	✓	✓	✓	✓	✓
platform_id	✓	✓	✓	✓	✓
platform_cabinet_id	✗	✓	✗	✗	✗
campaign_id	✗	✗	✓	✗	✗
ad_id	✗	✗	✗	✗	✓
platform_ad_id	✗	✗	✗	✗	✓
ad_status	✗	✗	✗	✗	✓
ad_cpm	✗	✗	✗	✗	✓
ad_budget	✗	✗	✗	✗	✓
exclude_crypto	✗	✗	✗	✗	✓
only_crypto	✗	✗	✗	✗	✓
additional_information	✗	✗	✗	✗	✓
target_langs	✗	✗	✗	✗	✓
target_countries	✗	✗	✗	✗	✓
target_locations	✗	✗	✗	✗	✓
target_channels	✗	✗	✗	✗	✓
target_user_channels	✗	✗	✗	✗	✓
target_search	✗	✗	✗	✗	✓
target_bots	✗	✗	✗	✗	✓

Примечания:

• Поле period_date всегда присутствует в ответе независимо от группировки
• При использовании комбинаций группировок (например, ["cabinet", "campaign"]) поля объединяются: если поле доступно хотя бы в одной из указанных группировок, оно будет присутствовать в ответе

---

Пагинация:

Для получения следующей страницы результатов используйте параметр cursor из ответа. Если cursor равен null, это означает, что достигнута последняя страница.

Пример запроса для следующей страницы:

POST https://client.adstat.pro/api/v1/stats/page
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "cursor": "eyJwZXJpb2QiOiIyMDI0LTA2LTA3In0="
}

:::

---

⚠️ Устаревший эндпоинт

Внимание!

Данный эндпоинт устарел и будет отключен 31.01.2026. Рекомендуется использовать /api/v1/stats/page.

POST report/tgview

Пример использования:

https://client.adstat.pro/api/report/tgview

Параметры:

Заголовки HTTP:

В заголовках HTTP запроса необходимо передать <access_token> в формате:

• Authorization: "Bearer <access_token>"

Тело запроса:

В теле HTTP запроса необходимо передать параметры получения статистики.

Описание параметров, передаваемых в тело запроса:

Поле	Тип	Описание
date	Объект	Интервал дат, определяющий временной период запроса.
date.date_from	Строка	Начальная дата и время в формате ISO 8601 (например, "2024-06-07T00:00:00.000Z").
date.date_to	Строка	Конечная дата и время в формате ISO 8601 (например, "2024-06-07T23:59:59.000Z").
platform	Массив чисел	Статичное значение равное всегда [10].
partner	Массив чисел	Статичное значение равное всегда [2].
campaign	Массив	Список идентификаторов кампаний. Может быть пустым массивом, если нужно получить данные по всем кампаний.
group_time	Число	Параметр группировки по времени. Значения: День- 1, Месяц - 2, Неделя - 3, Год - 4.
groupings	Массив объектов	Список объектов группировки данных. Каждый объект определяет параметр группировки.
groupings.name	Строка	Имя параметра для группировки (например, "date", "object" итд ).
groupings.type	Число	Тип группировки для параметра. Используется только для некоторых группировок (например, 1).
object	Массив	Список идентификаторов объектов рекламирования для плучения статистики по выбранным объектам. ["t.me/someobject", "..."]. Если нужно получить по всем объектам, то значение - []. Список объектов рекламирования можно получить в Список объектов рекламирования
sub_client	Массив	Внутренний параметр для технических нужд.
type_cab	null	Тип кабинета. Статичное значение - всегда null.
currency	Строка	Валюта, в которой будут представлены данные. Статичное значение - всегда RUB
account_uids	Массив	Список идентификаторов кабинетов, предназначенный для фильтрации статистики по отдельным кабинетам.Может быть пустым массивом [], если нужно получить данные по всем кабинетам. Если по отдельным кабинетам - ["ACC0000", "..."]. Список содержащий account_uids кабинетов можно получить в Список кабинетов

Подробное описание параметров:

Параметр groupings:

Пример 1: Статистика, сгруппированная только по дате:

{
	"others_params": "others params",
	"groupings": [{ "name": "date", "type": "<group_time>" }],
	"..": "others params"
}

Пример 2: Статистика, сгруппированная по нескольким параметрам:

• По объекту рекламирования: {"name": "object"}
• По объявлению: {"name": "campaign"}
• По кабинету: {"name": "account", "type": 1}

{
	"others_params": "others params",
	"groupings": [
		{ "name": "object" },
		{ "name": "campaign" },
		{ "name": "account", "type": 1 },
		{ "name": "date", "type": "<group_time>" }
	],
	"..": "others params"
}

Полный пример тела запроса:

{
	"date": {
		"date_from": "2024-06-07T00:00:00.000Z",
		"date_to": "2024-06-07T23:59:59.000Z"
	},
	"platform": [10],
	"partner": [2],
	"campaign": [],
	"group_time": 1,
	"groupings": [
		{
			"name": "date",
			"type": 1
		},
		{
			"name": "partner"
		},
		{
			"name": "platform"
		},
		{
			"name": "sub_client"
		}
	],
	"object": [],
	"sub_client": [],
	"type_cab": null,
	"currency": "RUB",
	"account_uids": []
}

Пример успешного ответа:

{
	"results": [
		{
			"account_name": "SOME_Test",
			"account_uid": "ACC0000000",
			"action_type": "join",
			"ad_id": 999999999,
			"ad_text": "example ad_text",
			"ad_type": "target_channels",
			"button_type": null,
			"campaign_plat": "example campaign plat",
			"clicks": 0,
			"cpc": 0.0,
			"cpm": 1.33,
			"ctr": 0.0,
			"cvr": 0.0,
			"date": "2024-06-09",
			"goals": 0.0,
			"impressions": 1.0,
			"object": "t.me/example",
			"opened": null,
			"price_target": 0.0,
			"promote_url": "t.me/example",
			"spent": 0.004,
			"target_bots": [],
			"target_channels": [],
			"target_countries": [],
			"target_langs": ["Russian"],
			"target_search": ["Russian"],
			"target_topics": ["Offers & Promotions"],
			"target_user_channels": [],
			"target_user_locations": [],
			"unit": 1016091001563,
			"website_name": null
		}
	]
}

Структура ответа:

Поля объекта результата:

Поле	Тип	Описание
account_name	Строка	Название аккаунта.
account_uid	Строка	Уникальный идентификатор аккаунта.
action_type	Строка или null	Тип целевого действия.
ad_id	Число	Уникальный идентификатор объявления.
ad_text	Строка	Текст креатива.
ad_type	Строка	Тип объявления (например, target_channels, target_users, target_search, target_bots).
button_type	Строка или null	Текст кнопки.
campaign_plat	Строка	Наименование объявления.
clicks	Число	Клики.
cpc	Число	Стоимость за клик (CPC).
cpm	Число	Стоимость тысячи показов (CPM).
ctr	Число	Коэффициент кликабельности (CTR).
cvr	Число	Коэффициент конверсии (CVR).
date	Строка	Дата в формате "YYYY-MM-DD".
goals	Число	Цели.
impressions	Число	Количество показов объявления.
object	Строка	Объект рекламирования.
opened	Число или null	Открытий видео.
price_target	Число	Цена за цель.
promote_url	Строка	Конечный URL рекламируего объекта.
spent	Число	Расходы.
target_bots	Массив строк	Список ботов, на которые таргетируется объявление.
target_channels	Массив строк	Список каналов, на которые таргетируется объявление.
target_countries	Массив строк	Список стран, на которые таргетируется объявление.
target_langs	Массив строк	Список языков, на которые таргетируется объявление.
target_search	Массив строк	Список поисковых запросов, на которые таргетируется объявление.
target_topics	Массив строк	Список топиков, на которые таргетируется объявление.
target_user_channels	Массив строк	Список каналов, на которые таргетируется объявление.
target_user_locations	Массив строк	Список местоположений, на которые таргетируется объявление.
unit	Число	Внутренний параметр для технических нужд.
website_name	Строка	Название вебсайта.

---

Список объектов рекламирования

INFO

GET report/objects

Пример использования:

https://client.adstat.pro/api/report/objects

Параметры запроса:

Заголовки HTTP:

В заголовках HTTP запроса необходимо передать <access_token> в формате:

• Authorization: "Bearer <access_token>"

Пример успешного ответа:

["t.me/object", "https://example.ru"]