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

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

INFO

POST /api/v1/stats/page

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

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

Параметры:

В заголовках 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"	Да
grouping	string[]	Группировка данных по сущностям. Возможные значения: "cabinet", "ad_object", "ad"	Нет
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	Токен пагинации для получения следующей страницы результатов	Нет

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

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": "partner_id",
			"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": "title",
			"type": "string"
		},
		{
			"key": "text",
			"type": "string"
		},
		{
			"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": "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"
		}
	],
	"rows": [
		{
			"period_date": "2025-05-01T00:00:00",
			"original_spent": "0.395640",
			"original_currency": "EUR",
			"exchanged_spent": "0.395640",
			"exchange_currency": "EUR",
			"views": 157,
			"clicks": 12,
			"actions": 3,
			"video_opens": 0,
			"ctr": "7.6",
			"cpc": "0.0329700000",
			"cpm": "2.5200000000",
			"cpa": "0.1318800000",
			"cvr": "25.0",
			"partner_id": 10956,
			"campaign_id": 176,
			"platform_id": 10,
			"ad_object": "t.me/cute_cats_bot",
			"ad_id": 1620160,
			"platform_ad_id": 1682,
			"platform_cabinet_id": "ACC01609",
			"title": "🐱 Милые котики каждый день!",
			"text": "😻 Получайте фото самых милых котиков прямо в Telegram!",
			"promote_url": "t.me/cute_cats_bot?start=cats123",
			"target_type": "target_users",
			"website_name": null,
			"media_type": "image",
			"views_limit_per_user": 3,
			"website_button_type": null,
			"action_type": "start_bot",
			"exclude_crypto": false,
			"only_crypto": false,
			"target_langs": ["Russian"],
			"target_countries": ["RU"],
			"target_locations": ["Moscow"],
			"target_channels": null,
			"target_user_channels": [],
			"target_topics": ["Pets & Animals", "Lifestyle", "Entertainment"],
			"target_search": null,
			"target_bots": null,
			"platform_cabinet_name": "Cats_Lovers_Studio"
		}
	],
	"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, %
cpc	string	Стоимость за клик	Цена клика (CPC)
cpm	string	Стоимость за 1000 показов	CPM
cpa	string	Стоимость за действие	Цена действия (CPA)
cvr	string	Коэффициент конверсии (в процентах)	CVR, %
partner_id	number	ID партнера	-
campaign_id	number	ID кампании	-
platform_id	number	ID платформы	-
ad_object	string	Объект рекламирования	URL
ad_id	number	ID объявления	-
platform_ad_id	number	ID объявления на платформе	-
platform_cabinet_id	string	ID кабинета на платформе	-
title	string | null	Название объявления	Наименование объявления
text	string | null	Текст объявления	Текст креатива
promote_url	string | null	URL рекламируемого объекта	URL
target_type	string | null	Тип таргетинга	Тип таргетинга
website_name	string | null	Название веб-сайта	Название сайта
media_type	string | null	Тип медиа	Тип медиа
views_limit_per_user	number	Лимит показов на пользователя	Частота показов
website_button_type	string | null	Тип кнопки веб-сайта	Текст кнопки
action_type	string | null	Тип действия	Тип действия
exclude_crypto	boolean	Исключить криптовалютные объявления	-
only_crypto	boolean	Только криптовалютные объявления	-
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	Целевые боты	-
platform_cabinet_name	string | null	Название кабинета на платформе	-

Пагинация:

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

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

{
  "cursor": "eyJwZXJpb2QiOiIyMDI0LTA2LTA3In0="
}

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

WARNING

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

INFO

POST report/tgview

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

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

Параметры:

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

• Authorization: "Bearer <access_token>"

В тело(body) 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 :

• Значение, когда необходимо получить статистику сгруппированную только по дате:

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

• Значение, когда необходимо получить статистику сгрупированную по -

Объекту рекламирования - {"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 запроса необходимо передать <access_token> в формате:

• Authorization: "Bearer <access_token>"

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

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