Working with statistics

🆕 New endpoint (recommended)

POST /api/v1/stats/page

Example usage:

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

Request parameters:

HTTP headers:

Pass <access_token> in the HTTP request headers in the following format:

• Authorization: "Bearer <access_token>"

Request body:

The HTTP request body contains parameters for retrieving statistics.

Parameter	Type	Description	Required
period_from	string	Start date of the period for statistics (ISO 8601)	Yes
period_to	string	End date of the period for statistics (ISO 8601)	Yes
period_grouping_unit	string	Time grouping unit. Possible values: "day", "week", "month", "year", "hour", "30_minutes", "5_minutes"	Yes
grouping	string[]	Data grouping by entities. Possible values: "cabinet", "ad_object", "ad", "campaign"	No
platform_cabinet_ids	string[]	Filter by platform cabinet IDs	No
ad_objects	string[]	Filter by ad objects	No
currency_code	string	Currency for financial metrics. Default: EUR. Available values: EUR, TON, USD, RUB, USDT, STAR	No
order_by	string	Result sort parameter. "period" — ascending by date, "-period" — descending by date	No
limit	number	Maximum number of records in the response (maximum: 500)	No
cursor	string	Pagination token for fetching the next page of results	No

Restrictions for detailed time grouping

When using period_grouping_unit values: "hour", "30_minutes", "5_minutes", the following restrictions apply:

• Data availability: data is available only for the last 5 days
• Maximum request period: the period between period_from and period_to cannot exceed 2 days

Example request:

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
}

Example successful response:

Expand to view response

{
	"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=="
}

Response structure:

Field	Type	Description
columns	object[]	Table column metadata (see structure below)
rows	object[]	Array of rows with statistics data (see fields below)
count	number	Total number of records in the result
cursor	string | null	Pagination token for the next page (base64 JSON or null for the last page)

Column structure (columns):

Field	Type	Description
key	string	Field identifier in the data
type	string	Field data type: "string", "number", "money", "date", "datetime", "boolean", "array"

Data fields in rows (rows):

The table below lists all possible fields that may appear in result rows depending on request parameters:

Field	Type	Description	Frontend label
period_date	string	Period date (ISO 8601)	Day/Week/Month/Year/Period
original_spent	string	Amount spent in the original currency	-
original_currency	string	Original currency	-
exchanged_spent	string	Amount spent in the report currency	Spend
exchange_currency	string	Report currency	-
views	number	Number of impressions	Impressions
clicks	number	Number of clicks	Clicks
actions	number	Number of actions	Actions
video_opens	number	Number of video opens	Video opens
ctr	string	Click-through rate (percentage)	CTR,% (Click-through rate: (Clicks/Impressions)*100)
cpc	string	Cost per click	CPC (Cost per click: Spend/Clicks)
cpm	string	Cost per 1,000 impressions (actual)	CPM (Cost per 1,000 impressions)
cpa	string	Cost per action	CPA (Cost per goal: Spend/Actions)
cvr	string	Conversion rate (percentage)	CVR,% (Conversion rate: (Actions/Clicks)*100)
campaign_id	number	Campaign ID	-
platform_id	number	Platform ID	-
ad_object	string	Ad object	Object
ad_id	number	Ad ID	-
platform_ad_id	number	Platform ad ID	-
platform_cabinet_id	string	Platform cabinet ID	-
ad_status	string	Ad status	-
ad_cpm	string	Cost per 1,000 impressions (set on the ad)	-
ad_budget	string	Ad budget	-
ad_title	string | null	Ad title	Ad name
ad_text	string | null	Ad text	Creative text
promote_url	string | null	Promoted object URL	URL
website_name	string | null	Website name	Site name
website_button_type	string | null	Website button type	Button text
views_limit_per_user	number	Impression limit per user	Impression frequency
action_type	string | null	Action type	Action type
exclude_crypto	boolean	Exclude cryptocurrency ads	-
only_crypto	boolean	Cryptocurrency ads only	-
additional_information	string | null	Additional information (erid token)	-
media_type	string | null	Media type	Media type
platform_cabinet_name	string | null	Platform cabinet name	Cabinet
campaign_name	string | null	Campaign name	Campaign name
target_type	string | null	Targeting type	Targeting type
target_langs	string[]	Target languages	-
target_countries	string[] | null	Target countries	-
target_locations	string[] | null	Target locations	-
target_channels	string[] | null	Target channels	-
target_user_channels	string[]	Target user channels	-
target_topics	string[] | null	Target topics	Interests
target_search	string[] | null	Target search queries	-
target_bots	string[] | null	Target bots	-

Field availability by grouping:

The table below shows which fields are returned in the API response depending on the grouping parameter value:

API field	No breakdown	By cabinets (["cabinet"])	By campaigns (["campaign"])	By objects (["ad_object"])	By ads (["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	✗	✗	✗	✗	✓

Notes:

• The period_date field is always present in the response regardless of grouping
• When using grouping combinations (for example, ["cabinet", "campaign"]), fields are merged: if a field is available in at least one of the specified groupings, it will be present in the response

---

Pagination:

To fetch the next page of results, use the cursor parameter from the response. If cursor is null, the last page has been reached.

Example request for the next page:

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

{
  "cursor": "eyJwZXJpb2QiOiIyMDI0LTA2LTA3In0="
}

:::

---

⚠️ Deprecated endpoint

Attention!

This endpoint is deprecated and will be disabled on 28.02.2026. We recommend using /api/v1/stats/page.

POST report/tgview

Example usage:

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

Parameters:

HTTP headers:

Pass <access_token> in the HTTP request headers in the following format:

• Authorization: "Bearer <access_token>"

Request body:

The HTTP request body must contain parameters for retrieving statistics.

Description of parameters passed in the request body:

Field	Type	Description
date	Object	Date interval defining the time period for the request.
date.date_from	String	Start date and time in ISO 8601 format (for example, "2024-06-07T00:00:00.000Z").
date.date_to	String	End date and time in ISO 8601 format (for example, "2024-06-07T23:59:59.000Z").
platform	Array of numbers	Static value always equal to [10].
partner	Array of numbers	Static value always equal to [2].
campaign	Array	List of campaign identifiers. May be an empty array if you need data for all campaigns.
group_time	Number	Time grouping parameter. Values: Day — 1, Month — 2, Week — 3, Year — 4.
groupings	Array of objects	List of data grouping objects. Each object defines a grouping parameter.
groupings.name	String	Parameter name for grouping (for example, "date", "object", etc.).
groupings.type	Number	Grouping type for the parameter. Used only for some groupings (for example, 1).
object	Array	List of ad object identifiers to retrieve statistics for selected objects. ["t.me/someobject", "..."]. Use [] to retrieve data for all objects. You can get the list of ad objects in Ad object list
sub_client	Array	Internal parameter for technical needs.
type_cab	null	Cabinet type. Static value — always null.
currency	String	Currency in which data will be presented. Static value — always RUB
account_uids	Array	List of cabinet identifiers for filtering statistics by individual cabinets. May be an empty array [] to retrieve data for all cabinets. For individual cabinets — ["ACC0000", "..."]. You can get a list containing cabinet account_uids in Cabinet list

Detailed parameter description:

groupings parameter:

Example 1: Statistics grouped by date only:

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

Example 2: Statistics grouped by multiple parameters:

• By ad object: {"name": "object"}
• By ad: {"name": "campaign"}
• By cabinet: {"name": "account", "type": 1}

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

Full request body example:

{
	"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": []
}

Example successful response:

{
	"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
		}
	]
}

Response structure:

Result object fields:

Field	Type	Description
account_name	String	Account name.
account_uid	String	Unique account identifier.
action_type	String or null	Target action type.
ad_id	Number	Unique ad identifier.
ad_text	String	Creative text.
ad_type	String	Ad type (for example, target_channels, target_users, target_search, target_bots).
button_type	String or null	Button text.
campaign_plat	String	Ad name.
clicks	Number	Clicks.
cpc	Number	Cost per click (CPC).
cpm	Number	Cost per thousand impressions (CPM).
ctr	Number	Click-through rate (CTR).
cvr	Number	Conversion rate (CVR).
date	String	Date in "YYYY-MM-DD" format.
goals	Number	Goals.
impressions	Number	Number of ad impressions.
object	String	Ad object.
opened	Number or null	Video opens.
price_target	Number	Cost per goal.
promote_url	String	Final URL of the promoted object.
spent	Number	Spend.
target_bots	Array of strings	List of bots the ad targets.
target_channels	Array of strings	List of channels the ad targets.
target_countries	Array of strings	List of countries the ad targets.
target_langs	Array of strings	List of languages the ad targets.
target_search	Array of strings	List of search queries the ad targets.
target_topics	Array of strings	List of topics the ad targets.
target_user_channels	Array of strings	List of channels the ad targets.
target_user_locations	Array of strings	List of locations the ad targets.
unit	Number	Internal parameter for technical needs.
website_name	String	Website name.

---

Ad object list

INFO

GET report/objects

Example usage:

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

Request parameters:

HTTP headers:

Pass <access_token> in the HTTP request headers in the following format:

• Authorization: "Bearer <access_token>"

Example successful response:

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