Documentation
API version 4 and Live 4
Methods
Disabled methods

CreateNewReport (Live)

Generates a campaign statistics report on the server.
Attention! 

This method is outdated and will soon be disabled. Use version 5 of the API.

When calling this method, error 59 is returned periodically.

For information about the compatibility of methods between versions Live 4 and 5, see the Migration guide.

Attention! Instead of generating a report, it is preferable to get statistics using the GetSummaryStat (Live)
[no-highlight[

Returns statistics for the specified campaigns for each day of the specified period.

More GetSummaryStat (Live)

]no-highlight]
and GetBannersStat (Live)
[no-highlight[

Returns statistics for the specified campaign for a period no longer than seven days.

More GetBannersStat (Live)

]no-highlight]
methods, if the information provided by them is detailed enough.
The method returns the ID of the future report. With this ID, you can find out whether the report is ready and get a link for downloading the report file (using the GetReportList
[no-highlight[

Returns a list of campaign statistics reports that have been generated or are being generated.

More GetReportList

]no-highlight]
method). The average time for generating a report is one to two minutes.

Restrictions

For a single campaign, a maximum of 300 calls of the CreateNewReport method are allowed per day.

For a single user, no more than five reports are stored on the server. On an attempt to create a sixth report, an error message is returned with error code 31. Reports are stored on the server for five hours, then deleted automatically. Use the DeleteReport
[no-highlight[

Deletes a campaign statistics report from the server.

More DeleteReport

]no-highlight]
method to delete a report manually.
Report period

The report period set by the StartDate and EndDate parameters must not be more than:

  • 367 days, for reports with data grouped by ads (clBanner), by keywords (clPhrase), by impression type (clImage) and/or by days.
  • 31 days, for reports with any other grouping.

If a longer report period is set, an error message is returned with code 5.

Statistics are available for the three years prior to the current month. For example: on September 15, 2016, you can get data starting from September 1, 2013.

Goals and conversions
To get data about visitors' behavior on the site (goal_id, session_depth, goal_conversion, goal_cost, goal_conversions_num, revenue, and roi), a Yandex.Metrica counter must be installed on the advertiser's site. The counter number must be specified in the AdditionalMetrikaCounters
[no-highlight[

Array containing IDs of Yandex.Metrica counters.

To delete counter IDs, pass an empty array. If the parameter is omitted, IDs are not changed.

Required

No

]no-highlight]
campaign parameter.

For goal_id, goal_conversion, goal_cost, goal_conversions_num, revenue, and roi it is also required that the counter has goals set up. For revenue and roi, the counter code must transmit the order price.

Average position

Data on an ad's average position is available starting from November 1, 2014.

Device type

Data on the device type is available starting from November 1, 2014.

User's gender and age group

Data on the user's gender and age group is available starting from July 22, 2015.

Type of operating system and type of connection

OS type data is available starting from September 15, 2015.

Connection type data is available starting from October 16, 2015.

Bid adjustment

Data for a retargeting condition used for applying bid adjustments for website users is available starting from July 22, 2016.

New in the Live 4 version

Added the input parameters Currency
[no-highlight[

The currency to use for amounts in the response.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign operates using a real currency, returned values are converted from the campaign‘s currency to Yandex units (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the client‘s currency, an error is returned with code 245.

Required

No

]no-highlight]
, IncludeVAT
[no-highlight[

Calculate VAT for the cost of clicks in a currency — Yes/No. When the value is Yes, amounts shown in the response will include VAT. If omitted, Yes is assumed.

If the Currency parameter is omitted, the IncludeVAT parameter is ignored.

Required

No

]no-highlight]
, and IncludeDiscount
[no-highlight[

Calculate the discount for the cost of clicks in a currency — Yes/No.

When the value is Yes, the report will show amounts that include the discount (in other words, the amounts that are actually deducted from the campaign balance). When the value is No, the report will show amounts before the discount is applied. If omitted, Yes is assumed.

Note. For campaigns that operate in a currency, the discount is applied when the cost of a click is deducted (see the section Real currencies instead of Yandex units).

If the Currency parameter is omitted, the “No“ value is assumed.

Required

No

]no-highlight]
(also see the section Real currencies instead of Yandex units).
The goal_conversions_num
[no-highlight[

Number of goal visits (conversions).

]no-highlight]
indicator was added to the report. For the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter, the clGoalConversionsNum value was added.
The shows_average_position
[no-highlight[

Average position where the ad is displayed. Calculated using only displays on the first page of Yandex search results.

The top position is assigned the number 1.

]no-highlight]
and clicks_average_position
[no-highlight[Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results.]no-highlight]
indicators were added to the report. For the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter, the clAveragePosition value was added.
Added the device_type
[no-highlight[

The type of device the ad was shown on. Acceptable values: desktop/mobile/tablet.

]no-highlight]
indicator to the report. Added the clDeviceType value for the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter.
The revenue
[no-highlight[

Revenue (up to two decimal places) — the total of the order prices transmitted by the Yandex.Metrica counter.

]no-highlight]
and roi
[no-highlight[

The return on investment in advertising (up to two decimal places):

]no-highlight]
indicators were added to the report. Added the clROI value for the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter.
The age
[no-highlight[

User‘s age group. Possible values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN.

]no-highlight]
and gender
[no-highlight[

Gender of the user. Possible values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN.

]no-highlight]
indicators were added to the report. Added the clDemographics value for the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter. Added the Age
[no-highlight[

Select entries about ad displays to users in the specified age groups. The array can have the following values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN.

Required

No

]no-highlight]
and Gender
[no-highlight[

Select entries about ad displays to users of the specified gender. The array can have the following values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN.

Required

No

]no-highlight]
input parameters.
Added the mobile_platform
[no-highlight[

The type of operating system. Possible values: ANDROID, IOS, OS_TYPE_UNKNOWN.

]no-highlight]
and carrier_type
[no-highlight[

Type of connection. Possible values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

]no-highlight]
indicators to the report. Added the clMobilePlatofrm and clCarrierType values for the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter. Added the MobilePlatform
[no-highlight[

Select entries about ad displays on devices with the specified type of OS. The array can have the following values: ANDROID, IOS, OS_TYPE_UNKNOWN.

Filtration by the OS type is available only for campaigns with the type “Ads for mobile apps”.

Required

No

]no-highlight]
and CarrierType
[no-highlight[

Select entires about ad displays on the specified type of connection. The array can have the following values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

Filtration by the connection type is available only for campaigns with the type “Ads for mobile apps”.

Required

No

]no-highlight]
input parameters.
For “Dynamic text ads” campaigns, if the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
parameter is set to "clPhrase", the report contains entries with the WebpageID attribute showing the data source for generating dynamic ads.
The rl_adjustment_id
[no-highlight[

ID of a retargeting condition used for applying bid adjustments for website users.

]no-highlight]
indicator has been added to the report. The value "clAdjustment" has been added to the GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
input parameter.
Add the Video value for the stat_type
[no-highlight[

Format of the ad impression. Possible values: Text, Image, Video.

]no-highlight]
indicator.

Input data

The input data structure in JSON is shown below.

{
   "method": "CreateNewReport",
   "param": {
      /* NewReportInfo */
      "CampaignID
[no-highlight[

ID of the campaign that the report is being generated for.

Required

Yes

]no-highlight]
": (int), "StartDate
[no-highlight[

The start date of the report, YYYY-MM-DD.

Required

Yes

]no-highlight]
": (date), "EndDate
[no-highlight[

The end date of the report, YYYY-MM-DD.

Required

Yes

]no-highlight]
": (date), "GroupByColumns
[no-highlight[

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user‘s age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).

Required

No

]no-highlight]
": [ (string) ... ], "Limit
[no-highlight[

Total number of items from the database to display in the report (more than zero).

Parameters Limit and Offset are used for selecting entries by page.

Required

No

]no-highlight]
": (int), "Offset
[no-highlight[

Entry number to start the selection from (numbering starts from zero).

The Limit and Offset parameters are used for selecting entries by page.

Required

If the Limit parameter is set

]no-highlight]
": (int), "GroupByDate
[no-highlight[

Calculate cumulative statistics by time period:

  • day — By the day of the week (initial value).
  • week — By the week.
  • month — By the month.

This parameter should be set if the GroupByColumns array has the clDate value; otherwise, the parameter is ignored.

Required

No

]no-highlight]
": (string), "OrderBy
[no-highlight[

Names of indicators to sort report entries by. Acceptable values are listed in the description for the GroupByColumns parameter.

Required

No

]no-highlight]
": [ (string) ... ], "TypeResultReport
[no-highlight[

Report format. Currently, only the “xml” value is used.

Required

No

]no-highlight]
": (string), "CompressReport
[no-highlight[

Method for compressing the report:

  • 0 or omitted parameter — Do not compress.
  • 1 — Compress using gzip.

Required

No

]no-highlight]
": (int), "Filter
[no-highlight[

A NewReportFilterInfo object with parameters for filtering entries for the report. If omitted, entries will not be filtered.

Required

No

]no-highlight]
": { /* NewReportFilterInfo */ "PageType": (string), "PositionType": (string), "Banner": [ (long) ... ], "Geo": [ (int) ... ], "Phrase": [ (string) ... ], "PageName": [ (string) ... ], "StatGoals": [ (int) ... ], "WithImage": (string), "DeviceType": (string), "Age": [ (string) ... ], "Gender": [ (string) ... ], "MobilePlatform": [ (string) ... ], "CarrierType": [ (string) ... ] }, "Currency
[no-highlight[

The currency to use for amounts in the response.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign operates using a real currency, returned values are converted from the campaign‘s currency to Yandex units (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the client‘s currency, an error is returned with code 245.

Required

No

]no-highlight]
": (string), "IncludeVAT
[no-highlight[

Calculate VAT for the cost of clicks in a currency — Yes/No. When the value is Yes, amounts shown in the response will include VAT. If omitted, Yes is assumed.

If the Currency parameter is omitted, the IncludeVAT parameter is ignored.

Required

No

]no-highlight]
": (string), "IncludeDiscount
[no-highlight[

Calculate the discount for the cost of clicks in a currency — Yes/No.

When the value is Yes, the report will show amounts that include the discount (in other words, the amounts that are actually deducted from the campaign balance). When the value is No, the report will show amounts before the discount is applied. If omitted, Yes is assumed.

Note. For campaigns that operate in a currency, the discount is applied when the cost of a click is deducted (see the section Real currencies instead of Yandex units).

If the Currency parameter is omitted, the “No“ value is assumed.

Required

No

]no-highlight]
": (string) } }

Parameters are described below.

Parameter Description Required
NewReportInfo object
CampaignID

ID of the campaign that the report is being generated for.

Yes
StartDate

The start date of the report, YYYY-MM-DD.

Yes
EndDate

The end date of the report, YYYY-MM-DD.

Yes
GroupByColumns

Names of indicators to output in the report in addition to the statistical data. Possible values:

  • clBanner — ID of the ad, bannerID.
  • clDate — Date when statistics were collected, statDate.
  • clPage — Data about display sites, placeName and placeType.
  • clGeo — ID of the region for impressions, regionID.
  • clPhrase — A keyword ID (phraseID), a Yandex.Catalog category (rubricID), a retargeting ID (DictID), or the ID of a data source for generating dynamic ads (WebpageID).
  • clStatGoals — Date about Yandex.Metrica: goal_id, session_depth, goal_conversion, and goal_cost (see Goals and conversions).
  • clGoalConversionsNum — Data about Yandex.Metrica: the number of goal visits goal_conversions_num (see Goals and conversions). We recommend setting this value together with clStatGoals.
  • clPositionType — Display position, position_type.
  • clImage — Format of the ad display stat_type, as well as the ad ID bannerID (the clBanner value is automatically added to the input data).
  • clAveragePosition — The average ad display position shows_average_position and the average position of clicks on the ad clicks_average_position. To get these indicators for each ad individually, specify the clAveragePosition value together with clBanner.
  • clDeviceType — The type of device the ad is shown on.
  • clROI — The income (revenue) and return on investment (roi). See Goals and conversions.
  • clDemographics — The user's age group (age) and gender (gender).
  • clMobilePlatform — The OS type (mobile_plaform). Available only for campaigns with the type “Ads for mobile apps”.
  • clCarrierType — The type of connection (carrier_type). Available only for campaigns with the type “Ads for mobile apps”.
  • clAdjustment — ID of the retargeting condition rl_adjustment_id used for applying bid adjustments (this indicator is only available for “Text & Image Ads” or “Ads for mobile apps” campaigns).
No
GroupByDate

Calculate cumulative statistics by time period:

  • day — By the day of the week (initial value).
  • week — By the week.
  • month — By the month.

This parameter should be set if the GroupByColumns array has the clDate value; otherwise, the parameter is ignored.

No
OrderBy

Names of indicators to sort report entries by. Acceptable values are listed in the description for the GroupByColumns parameter.

No
Limit

Total number of items from the database to display in the report (more than zero).

Parameters Limit and Offset are used for selecting entries by page.
No
Offset

Entry number to start the selection from (numbering starts from zero).

The Limit and Offset parameters are used for selecting entries by page.

If the Limit parameter is set
TypeResultReport Report format. Currently, only the “xml” value is used.No
CompressReport

Method for compressing the report:

  • 0 or omitted parameter — Do not compress.
  • 1 — Compress using gzip.
No
Filter A NewReportFilterInfo object with parameters for filtering entries for the report. If omitted, entries will not be filtered.No
Currency

The currency to use for amounts in the response.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign operates using a real currency, returned values are converted from the campaign's currency to Yandex units (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the client's currency, an error is returned with code 245.

No
IncludeVAT

Calculate VAT for the cost of clicks in a currency — Yes/No. When the value is Yes, amounts shown in the response will include VAT. If omitted, Yes is assumed.

If the Currency parameter is omitted, the IncludeVAT parameter is ignored.

No
IncludeDiscount

Calculate the discount for the cost of clicks in a currency — Yes/No.

When the value is Yes, the report will show amounts that include the discount (in other words, the amounts that are actually deducted from the campaign balance). When the value is No, the report will show amounts before the discount is applied. If omitted, Yes is assumed.

Note. For campaigns that operate in a currency, the discount is applied when the cost of a click is deducted (see the section Real currencies instead of Yandex units).

If the Currency parameter is omitted, the "No" value is assumed.

No
NewReporFiltertInfo object
PageType

Filter entries by the type of site where ads are displayed:

  • search — Yandex search and search sites within the Yandex Advertising Network.
  • context — Sites in the Yandex Advertising Network, other than search platforms.
  • all or omitted — On all types of sites.
No
PositionType

Filter entries based on the display block:

  • premium — In Premium Placement.
  • other — Everywhere other than Premium Placement.
No
Banner Array of ad IDs. Selects entries about the display of the specified ads.No
Geo Array of region IDs. Selects entries about ad displays in the specified regions.No
Phrase

Array of strings. Selects entries about ad displays for the keywords that contain any of the specified strings as substrings (not case-sensitive).

Note. 
  • This parameter can only be set for campaigns with the type “Text & Image Ads” or “Ads for mobile apps”.

  • The parameter is ignored if "clPhrase" is omitted in the GroupByColumns parameter.
No
PageName

Array of site names. Selects entries about ad displays on the specified sites.

The Yandex search site has the name “Yandex”. For other sites, the domains are specified that are registered in Yandex.Direct, such as “mail.ru” and “nigma.ru”.

No
StatGoals

ID of the Yandex.Metrica goal (specified as an array item). More than one ID is not allowed.

If omitted, the Yandex.Metrica indicators in the report contain aggregated data for all goals.

Use the GetStatGoals (Live)
[no-highlight[

Returns information about the Yandex.Metrica goals that are available for the campaign.

More GetStatGoals (Live)

]no-highlight]
method to obtain a list of goals.
No
WithImage Select entries about ad displays either with or without images. Possible values: yes – with images; no – text; both – all (text, image, and video).No
DeviceType

Select entries about ad displays on a specific type of device. Acceptable values: desktop/mobile/tablet.

No
Age Select entries about ad displays to users in the specified age groups. The array can have the following values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN.No
Gender Select entries about ad displays to users of the specified gender. The array can have the following values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN.No
MobilePlatform

Select entries about ad displays on devices with the specified type of OS. The array can have the following values: ANDROID, IOS, OS_TYPE_UNKNOWN.

Filtration by the OS type is available only for campaigns with the type “Ads for mobile apps”.

No
CarrierType

Select entires about ad displays on the specified type of connection. The array can have the following values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

Filtration by the connection type is available only for campaigns with the type “Ads for mobile apps”.

No

Output data

The method returns the ID of the future report, as shown in the following example.

{
   "data": 137456
}

Examples of input data

{
   'CampaignID': 1327944,
   'StartDate': '2013-05-01',
   'EndDate': '2013-05-31',
   'GroupByColumns': [
      'clBanner',
      'clStatGoals',
      'clGoalConversionsNum',
      'clAveragePosition',
      'clROI'
   ],
   'Filter': {
      'PageType': 'search',
      'PositionType': 'other',
      'Banner': [1974642, 20920155, 20155899, 64654],
      'Geo': [213],
      'Phrase': [u'refrigerator'],
      'PageName': [u'Yandex','nigma.ru'],
      'StatGoals': [18565]
   },
   'Limit': 5000,
   'Offset': 30000,
   'GroupByDate': 'week',
   'OrderBy': ['clBanner'],
   'TypeResultReport': 'xml',
   'CompressReport': 1
}
array(
   'CampaignID' => 1327944,
   'StartDate' => '2013-05-01',
   'EndDate' => '2013-05-31',
   'GroupByColumns' => array(
      'clBanner',
      'clStatGoals',
      'clGoalConversionsNum',
      'clAveragePosition',
      'clROI'
   ),
   'Filter' => array(
      'PageType' => 'search',
      'PositionType' => 'other',
      'Banner' => array(1974642, 20920155, 20155899, 64654),
      'Geo' => array(213),
      'Phrase' => array('refrigerator'),
      'PageName' => array('Yandex','nigma.ru'),
      'StatGoals' => array(18565)
   ),
   'Limit' => 5000,
   'Offset' => 30000,
   'GroupByDate' => 'week',
   'OrderBy' => array('clBanner'),
   'TypeResultReport' => 'xml',
   'CompressReport' => 1
)
{
   'CampaignID' => 1327944,
   'StartDate' => '2013-05-01',
   'EndDate' => '2013-05-31',
   'GroupByColumns' => [
      'clBanner',
      'clStatGoals',
      'clGoalConversionsNum',
      'clAveragePosition',
      'clROI'
   ],
   'Filter' => {
      'PageType' => 'search',
      'PositionType' => 'other',
      'Banner' => [1974642, 20920155, 20155899, 64654],
      'Geo' => [213],
      'Phrase' => ['refrigerator'],
      'PageName' => ['Yandex','nigma.ru'],
      'StatGoals' => [18565]
   },
   'Limit' => 5000,
   'Offset' => 30000,
   'GroupByDate' => 'week',
   'OrderBy' => ['clBanner'],
   'TypeResultReport' => 'xml',
   'CompressReport' => 1
}

Sample report

A sample report in XML format is shown below.

<?xml version="1.0" encoding="UTF-8" ?>
<report> 
   <reportID
[no-highlight[

ID of the report.

]no-highlight]
>1234</reportID> <campaignID
[no-highlight[

The campaign ID.

]no-highlight]
>1234567</campaignID> <startDate
[no-highlight[

The start date of the report, YYYY-MM-DD.

]no-highlight]
>2013-05-01</startDate> <endDate
[no-highlight[

The end date of the report, YYYY-MM-DD.

]no-highlight]
>2013-05-31</endDate> <phrasesDict
[no-highlight[

Keyword dictionary. Contains information about objects in the report: keywords, Yandex.Catalog categories, retargetings, and targeting conditions for dynamic text ads.

]no-highlight]
> <phrase
[no-highlight[

Information about a keyword, category, retargeting, or targeting condition in the type, phraseID, DictID, WebpageID и value attributes.

]no-highlight]
type
[no-highlight[

Contains the value “phrase” in entries about keywords, “autotargeting” in entries about autotargeting, “rubric” in entries about Yandex.Catalog categories, “retargeting” in entries about retargetings, or “webpage” in entries about the data source for dynamic text ads.

]no-highlight]
="phrase" phraseID
[no-highlight[

ID of the keyword in the report.

1 — For additional relevant keywords.

11 — For autotargeting.

The phraseID identifier exists only within the report and does not match the keyword ID in Yandex.Direct. It is used for standardizing report data and links the phrase and row elements.

]no-highlight]
="2" value
[no-highlight[

The keyword text, or the number of a Yandex.Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords).

]no-highlight]
="refrigeration equipment" /> <phrase
[no-highlight[

Information about a keyword, category, retargeting, or targeting condition in the type, phraseID, DictID, WebpageID и value attributes.

]no-highlight]
type
[no-highlight[

Contains the value “phrase” in entries about keywords, “autotargeting” in entries about autotargeting, “rubric” in entries about Yandex.Catalog categories, “retargeting” in entries about retargetings, or “webpage” in entries about the data source for dynamic text ads.

]no-highlight]
="retargeting" DictID
[no-highlight[

ID of the retargeting in the report.

Exists only within the report and does not match the retargeting ID in Yandex.Direct. Used for standardizing report data; links the phrase and row elements.

]no-highlight]
="912" value
[no-highlight[

The keyword text, or the number of a Yandex.Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords).

]no-highlight]
="retargeting: order incomplete" /> <phrase
[no-highlight[

Information about a keyword, category, retargeting, or targeting condition in the type, phraseID, DictID, WebpageID и value attributes.

]no-highlight]
type
[no-highlight[

Contains the value “phrase” in entries about keywords, “autotargeting” in entries about autotargeting, “rubric” in entries about Yandex.Catalog categories, “retargeting” in entries about retargetings, or “webpage” in entries about the data source for dynamic text ads.

]no-highlight]
="webpage" WebpageID
[no-highlight[

ID of the data source for generating dynamic ads:

  • ID of the targeting condition for dynamic ads, if the data source is website pages.

  • ID of the filter, if the data source is a feed with product offers. You can only manage filters in the web interface at this time.

]no-highlight]
="258" value
[no-highlight[

The keyword text, or the number of a Yandex.Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords).

]no-highlight]
="tablets" /> <phrase
[no-highlight[

Information about a keyword, category, retargeting, or targeting condition in the type, phraseID, DictID, WebpageID и value attributes.

]no-highlight]
type
[no-highlight[

Contains the value “phrase” in entries about keywords, “autotargeting” in entries about autotargeting, “rubric” in entries about Yandex.Catalog categories, “retargeting” in entries about retargetings, or “webpage” in entries about the data source for dynamic text ads.

]no-highlight]
="autotargeting" phraseID
[no-highlight[

ID of the keyword in the report.

1 — For additional relevant keywords.

11 — For autotargeting.

The phraseID identifier exists only within the report and does not match the keyword ID in Yandex.Direct. It is used for standardizing report data and links the phrase and row elements.

]no-highlight]
="11" value
[no-highlight[

The keyword text, or the number of a Yandex.Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords).

]no-highlight]
="---autotargeting" /> </phrasesDict> <stat
[no-highlight[

Statistical data.

]no-highlight]
> <row
[no-highlight[

Statistics entry. The contents depend on the input parameters.

]no-highlight]
bannerID
[no-highlight[

The ad ID.

]no-highlight]
="123456" phraseID
[no-highlight[

The keyword ID in the report (see the phrasesDict element).

The phraseID identifier exists only within the report and does not match the keyword ID in Yandex.Direct. It is used for standardizing report data and links the phrase and row elements.

]no-highlight]
="2" phrase_id
[no-highlight[

ID of the keyword, autotargeting, or category in Yandex.Direct.

The ID might not exist in Yandex.Direct when the report is being generated. This is because the IDs change when keywords are edited, and are deleted when keywords are removed.

]no-highlight]
="538205157" statDate
[no-highlight[

The data statistics are provided for. If the GroupByDate input parameter has the value “week” or “month”, the first date of the week or month is specified.

]no-highlight]
="2013-05-15" sum_search
[no-highlight[

The total cost of clicks on search (in the currency specified in the Currency input parameter).

See the Notes below.

]no-highlight]
="10" sum_context
[no-highlight[

The total cost of clicks in the Yandex Advertising Network (in the currency specified in the Currency input parameter).

See the Notes below.

]no-highlight]
="2" shows_search
[no-highlight[

Number of impressions in the search.

]no-highlight]
="1000" shows_context
[no-highlight[

Number of impressions in the Yandex Advertising Network.

]no-highlight]
="123" clicks_search
[no-highlight[

Number of clicks in the search.

]no-highlight]
="100" clicks_context
[no-highlight[

Number of clicks in the Yandex Advertising Network.

]no-highlight]
="23" sum
[no-highlight[

The total cost of clicks deducted from the campaign balance (in the currency specified in the Currency input parameter).

See the Notes below.

]no-highlight]
="12" shows
[no-highlight[

Number of impressions1.

]no-highlight]
="1234" clicks
[no-highlight[

Number of clicks1.

]no-highlight]
="123" regionID
[no-highlight[

ID of the display region.

]no-highlight]
="1" placeName
[no-highlight[

Name of the site where the ad is being displayed.

]no-highlight]
="Yandex" placeType
[no-highlight[

Type of display platform: “search” — the search platform (including Yandex search and search sites in the Yandex Advertising Network), or “context” — a site in the Yandex Advertising Network.

]no-highlight]
="search" goal_id
[no-highlight[

The ID of the goal in Yandex.Metrica, if it was passed in the StatGoals input parameter.

0 — If the ID was not passed. In this case, the other Yandex.Metrica indicators contain aggregated data for all goals.

]no-highlight]
="18565" goal_conversion
[no-highlight[

The percentage of goal visits as part of the total number of visits.

]no-highlight]
="25.91" goal_cost
[no-highlight[

The average cost per conversion: the ratio of the cost of clicks to the number of conversions.

]no-highlight]
="1.54" session_depth
[no-highlight[

Session depth for the site.

]no-highlight]
="9.35" goal_conversions_num
[no-highlight[

Number of goal visits (conversions).

]no-highlight]
="28" revenue
[no-highlight[

Revenue (up to two decimal places) — the total of the order prices transmitted by the Yandex.Metrica counter.

]no-highlight]
="245.25" roi
[no-highlight[

The return on investment in advertising (up to two decimal places):

]no-highlight]
="3.77" position_type
[no-highlight[

The ad display block: “premium” for Premium Placement, or “other” for other ad blocks.

]no-highlight]
="premium" stat_type
[no-highlight[

Format of the ad impression. Possible values: Text, Image, Video.

]no-highlight]
="Text" shows_average_position
[no-highlight[

Average position where the ad is displayed. Calculated using only displays on the first page of Yandex search results.

The top position is assigned the number 1.

]no-highlight]
="4.87" clicks_average_position
[no-highlight[Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results.]no-highlight]
="4.95" device_type
[no-highlight[

The type of device the ad was shown on. Acceptable values: desktop/mobile/tablet.

]no-highlight]
="desktop" age
[no-highlight[

User‘s age group. Possible values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN.

]no-highlight]
="AGE_25_34" gender
[no-highlight[

Gender of the user. Possible values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN.

]no-highlight]
="GENDER_FEMALE" mobile_platform
[no-highlight[

The type of operating system. Possible values: ANDROID, IOS, OS_TYPE_UNKNOWN.

]no-highlight]
="IOS" carrier_type
[no-highlight[

Type of connection. Possible values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

]no-highlight]
="STATIONARY" rl_adjustment_id
[no-highlight[

ID of a retargeting condition used for applying bid adjustments for website users.

]no-highlight]
="14777"/> <row
[no-highlight[

Statistics entry. The contents depend on the input parameters.

]no-highlight]
bannerID
[no-highlight[

The ad ID.

]no-highlight]
="123457" DictID
[no-highlight[

The retargeting ID in the report (see the phrasesDict element).

Exists only within the report and does not match the retargeting ID in Yandex.Direct. Used for standardizing report data; links the phrase and row elements.

]no-highlight]
="912" RetargetingID
[no-highlight[

Retargeting ID in Yandex.Direct.

]no-highlight]
="3097" statDate
[no-highlight[

The data statistics are provided for. If the GroupByDate input parameter has the value “week” or “month”, the first date of the week or month is specified.

]no-highlight]
="2013-05-25" sum_search
[no-highlight[

The total cost of clicks on search (in the currency specified in the Currency input parameter).

See the Notes below.

]no-highlight]
="0" sum_context
[no-highlight[

The total cost of clicks in the Yandex Advertising Network (in the currency specified in the Currency input parameter).

See the Notes below.

]no-highlight]
="96.35" shows_search
[no-highlight[

Number of impressions in the search.

]no-highlight]
="0" shows_context
[no-highlight[

Number of impressions in the Yandex Advertising Network.

]no-highlight]
="755" clicks_search
[no-highlight[

Number of clicks in the search.

]no-highlight]
="0" clicks_context
[no-highlight[

Number of clicks in the Yandex Advertising Network.

]no-highlight]
="57" sum
[no-highlight[

The total cost of clicks deducted from the campaign balance (in the currency specified in the Currency input parameter).

See the Notes below.

]no-highlight]
="96.35" shows
[no-highlight[

Number of impressions1.

]no-highlight]
="755" clicks
[no-highlight[

Number of clicks1.

]no-highlight]
="57" regionID
[no-highlight[

ID of the display region.

]no-highlight]
="1" placeName
[no-highlight[

Name of the site where the ad is being displayed.

]no-highlight]
="catalog.tut.by" placeType
[no-highlight[

Type of display platform: “search” — the search platform (including Yandex search and search sites in the Yandex Advertising Network), or “context” — a site in the Yandex Advertising Network.

]no-highlight]
="context" goal_id
[no-highlight[

The ID of the goal in Yandex.Metrica, if it was passed in the StatGoals input parameter.

0 — If the ID was not passed. In this case, the other Yandex.Metrica indicators contain aggregated data for all goals.

]no-highlight]
="18565" goal_conversion
[no-highlight[

The percentage of goal visits as part of the total number of visits.

]no-highlight]
="28.88" revenue
[no-highlight[

Revenue (up to two decimal places) — the total of the order prices transmitted by the Yandex.Metrica counter.

]no-highlight]
="132.01" roi
[no-highlight[

The return on investment in advertising (up to two decimal places):

]no-highlight]
="3.12" goal_cost
[no-highlight[

The average cost per conversion: the ratio of the cost of clicks to the number of conversions.

]no-highlight]
="1.54" session_depth
[no-highlight[

Session depth for the site.

]no-highlight]
="9.39" goal_conversions_num
[no-highlight[

Number of goal visits (conversions).

]no-highlight]
="11" position_type
[no-highlight[

The ad display block: “premium” for Premium Placement, or “other” for other ad blocks.

]no-highlight]
="other" stat_type
[no-highlight[

Format of the ad impression. Possible values: Text, Image, Video.

]no-highlight]
="Image" device_type
[no-highlight[

The type of device the ad was shown on. Acceptable values: desktop/mobile/tablet.

]no-highlight]
="mobile" age
[no-highlight[

User‘s age group. Possible values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN.

]no-highlight]
="AGE_UNKNOWN" gender
[no-highlight[

Gender of the user. Possible values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN.

]no-highlight]
="GENDER_UNKNOWN" mobile_platform
[no-highlight[

The type of operating system. Possible values: ANDROID, IOS, OS_TYPE_UNKNOWN.

]no-highlight]
="ANDROID" carrier_type
[no-highlight[

Type of connection. Possible values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

]no-highlight]
="CELLULAR"/> </stat> </report>

The information output in the report is described below.

Element/attribute Description Output condition
report element
reportID ID of the report.
campaignID The campaign ID.
startDate The start date of the report, YYYY-MM-DD.
endDate The end date of the report, YYYY-MM-DD.
phrasesDict Keyword dictionary. Contains information about objects in the report: keywords, Yandex.Catalog categories, retargetings, and targeting conditions for dynamic text ads.
stat Statistical data.
phrasesDict element
phrase Information about a keyword, category, retargeting, or targeting condition in the type, phraseID, DictID, WebpageID и value attributes.
type Contains the value “phrase” in entries about keywords, “autotargeting” in entries about autotargeting, “rubric” in entries about Yandex.Catalog categories, “retargeting” in entries about retargetings, or “webpage” in entries about the data source for dynamic text ads.
phraseID

ID of the keyword in the report.

1 — For additional relevant keywords.

11 — For autotargeting.

The phraseID identifier exists only within the report and does not match the keyword ID in Yandex.Direct. It is used for standardizing report data and links the phrase and row elements.

rubricID

ID of the category in the report.

Exists only within the report and does not match the category ID in Yandex.Direct. Used for standardizing report data; links the phrase and row elements.

DictID

ID of the retargeting in the report.

Exists only within the report and does not match the retargeting ID in Yandex.Direct. Used for standardizing report data; links the phrase and row elements.

WebpageID

ID of the data source for generating dynamic ads:

  • ID of the targeting condition for dynamic ads, if the data source is website pages.

  • ID of the filter, if the data source is a feed with product offers. You can only manage filters in the web interface at this time.

value

The keyword text, or the number of a Yandex.Catalog category, or the name of a retargeting condition, or the name of a mobile app category, or the name of a targeting condition for dynamic ads, or the name of a filter, or the value “Automatically added keywords” (for additional relevant keywords).

stat element
row Statistics entry. The contents depend on the input parameters.
sum

The total cost of clicks deducted from the campaign balance (in the currency specified in the Currency input parameter).

See the Notes below.

shows Number of impressions 1
[no-highlight[

The values of the sum, shows and clicks parameters depend on the PageType input parameter:

  • when the value is “all” or PageType is omitted, cumulative data is given for the search and the Yandex Advertising Network. However, data is given separately for the search and the Yandex Advertising Network in the parameters sum_search, shows_search, clicks_search, sum_context, shows_context, and clicks_context.
  • If the value is “search”, data is provided for Yandex search and search sites in the Yandex Advertising Network.
  • If the value is “context”, data is provided for sites in the Yandex Advertising Network, other than search sites.
]no-highlight]
.
clicks Number of clicks 1
[no-highlight[

The values of the sum, shows and clicks parameters depend on the PageType input parameter:

  • when the value is “all” or PageType is omitted, cumulative data is given for the search and the Yandex Advertising Network. However, data is given separately for the search and the Yandex Advertising Network in the parameters sum_search, shows_search, clicks_search, sum_context, shows_context, and clicks_context.
  • If the value is “search”, data is provided for Yandex search and search sites in the Yandex Advertising Network.
  • If the value is “context”, data is provided for sites in the Yandex Advertising Network, other than search sites.
]no-highlight]
.
bannerID The ad ID. In the GroupByColumns parameter, the value of “clBanner” or “clImage” is specified.
phraseID

The keyword ID in the report (see the phrasesDict element).

The phraseID identifier exists only within the report and does not match the keyword ID in Yandex.Direct. It is used for standardizing report data and links the phrase and row elements.

In the GroupByColumns input parameter, the “clPhrase” value is specified, and the entry also contains information about the keyword or Yandex.Catalog category (but not about retargeting).

phrase_id

ID of the keyword, autotargeting, or category in Yandex.Direct.

The ID might not exist in Yandex.Direct when the report is being generated. This is because the IDs change when keywords are edited, and are deleted when keywords are removed.

In the GroupByColumns input parameter, the “clPhrase” and “clBanner” values are both set, and the entry contains information about the keyword or Yandex.Catalog category (but not about retargeting).

Attention! This indicator is output to the report beginning with the Live 4 version.
rubricID

ID of the Yandex.Catalog category in the report (see the phrasesDict element).

Exists only within the report and does not match the category ID in Yandex.Direct. Used for standardizing report data; links the phrase and row elements.

In the GroupByColumns input parameter, the “clPhrase” value is specified, and the entry contains information about the Yandex.Catalog category.

DictID

The retargeting ID in the report (see the phrasesDict element).

Exists only within the report and does not match the retargeting ID in Yandex.Direct. Used for standardizing report data; links the phrase and row elements.

In the GroupByColumns input parameter, the “clPhrase” value is set, and the entry contains information about retargeting.

WebpageID

ID of the data source for generating dynamic ads:

  • ID of the targeting condition for dynamic ads, if the data source is website pages.

  • ID of the filter, if the data source is a feed with product offers. You can only manage filters in the web interface at this time.

The GroupByColumns input parameter is set to “clPhrase”, and the entry contains information about the data source for generating dynamic ads.

RetargetingID Retargeting ID in Yandex.Direct. In the GroupByColumns input parameter, the “clPhrase” value is set, and the entry contains information about retargeting.
statDate The data statistics are provided for. If the GroupByDate input parameter has the value “week” or “month”, the first date of the week or month is specified.In the GroupByColumns array, the value “clDate” is present.
sum_search

The total cost of clicks on search (in the currency specified in the Currency input parameter).

See the Notes below.

The PageType input parameter is omitted or has the value “all”.
sum_context

The total cost of clicks in the Yandex Advertising Network (in the currency specified in the Currency input parameter).

See the Notes below.

shows_search

Number of impressions in the search.

shows_context Number of impressions in the Yandex Advertising Network.
clicks_search Number of clicks in the search.
clicks_context Number of clicks in the Yandex Advertising Network.
regionID ID of the display region. In the GroupByColumns array, the “clGeo” value is present.
placeName Name of the site where the ad is being displayed.In the GroupByColumns array, the value “clPage” is present.
placeType Type of display platform: “search” — the search platform (including Yandex search and search sites in the Yandex Advertising Network), or “context” — a site in the Yandex Advertising Network.
goal_id

The ID of the goal in Yandex.Metrica, if it was passed in the StatGoals input parameter.

0 — If the ID was not passed. In this case, the other Yandex.Metrica indicators contain aggregated data for all goals.

In the GroupByColumns array, the value “clStatGoals” is present.

goal_conversion The percentage of goal visits as part of the total number of visits.
goal_cost The average cost per conversion: the ratio of the cost of clicks to the number of conversions.
session_depth Session depth for the site.
goal_conversions_num

Number of goal visits (conversions).

In the GroupByColumns array, the value “clGoalConversionsNum” is present.

revenue Revenue (up to two decimal places) — the total of the order prices transmitted by the Yandex.Metrica counter.The GroupByColumns array has the “clROI” value.
roi

The return on investment in advertising (up to two decimal places):

position_type

The ad display block: “premium” for Premium Placement, or “other” for other ad blocks.

In the GroupByColumns array, the value “clPositionType” is present.
stat_type Format of the ad impression. Possible values: Text, Image, Video.In the GroupByColumns array, the “clImage” value is present.
shows_average_position

Average position where the ad is displayed. Calculated using only displays on the first page of Yandex search results.

The top position is assigned the number 1.

In the GroupByColumns array, the value “clAveragePosition” is present.
clicks_average_position Average position where the ad was clicked. Calculated using only clicks on the first page of Yandex search results.
device_type

The type of device the ad was shown on. Acceptable values: desktop/mobile/tablet.

The “clDeviceType” value is present in the GroupByColumns array.

age

User's age group. Possible values: AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45, AGE_UNKNOWN.

The “clDemographics” value is present in the GroupByColumns array.

gender

Gender of the user. Possible values: GENDER_MALE, GENDER_FEMALE, GENDER_UNKNOWN.

The “clDemographics” value is present in the GroupByColumns array.

mobile_platform

The type of operating system. Possible values: ANDROID, IOS, OS_TYPE_UNKNOWN.

The campaign type is “Ads for mobile apps”, and the GroupByColumns array has the value “clMobilePlatform”.

carrier_type

Type of connection. Possible values: CELLULAR (mobile), STATIONARY (wi-fi), CARRIER_TYPE_UNKNOWN.

The campaign type is “Ads for mobile apps”, and the GroupByColumns array has the value “clCarrierType”.

rl_adjustment_id

ID of a retargeting condition used for applying bid adjustments for website users.

The campaign type is “Text & Image Ads” or “Ads for mobile apps”, and the GroupByColumns array has the value “clAdjustment”.

Notes
  1. The values of sum, shows and clicks depend on the PageType input parameter:

    • when the value is “all” or PageType is omitted, cumulative data is given for the search and the Yandex Advertising Network. However, data is given separately for the search and the Yandex Advertising Network in sum_search, shows_search, clicks_search, sum_context, shows_context, and clicks_context.
    • If the value is “search”, data is provided for Yandex search and search sites in the Yandex Advertising Network.
    • If the value is “context”, data is provided for sites in the Yandex Advertising Network, other than search sites.
  2. The cost of clicks that is expressed in a currency may include or exclude VAT, depending on the value of the IncludeVAT
    [no-highlight[

    Calculate VAT for the cost of clicks in a currency — Yes/No. When the value is Yes, amounts shown in the response will include VAT. If omitted, Yes is assumed.

    If the Currency parameter is omitted, the IncludeVAT parameter is ignored.

    Required

    No

    ]no-highlight]
    input parameter.

    Cost of clicks with VAT = Cost of clicks without VAT × (1 + VAT rate)

  3. The cost of clicks that is expressed in a currency may or may not include the discount, depending on the value of the IncludeDiscount
    [no-highlight[

    Calculate the discount for the cost of clicks in a currency — Yes/No.

    When the value is Yes, the report will show amounts that include the discount (in other words, the amounts that are actually deducted from the campaign balance). When the value is No, the report will show amounts before the discount is applied. If omitted, Yes is assumed.

    Note. For campaigns that operate in a currency, the discount is applied when the cost of a click is deducted (see the section Real currencies instead of Yandex units).

    If the Currency parameter is omitted, the “No“ value is assumed.

    Required

    No

    ]no-highlight]
    input parameter.

    Cost of clicks before applying the discount = Cost of clicks actually deducted from the balance / (1 – Discount)

    Note. For campaigns that operate in a currency, the discount is applied when the cost of a click is deducted (see the section Real currencies instead of Yandex units).
  4. If the campaign operates in Yandex units and the Currency parameter is not set, the amounts are returned “as is”, without any other conversions.
  5. If the campaign operates in a currency and the Currency parameter is not set, the amounts are calculated as follows:

    CPC in Yandex units = CPC before applying discount in currency with VAT / Exchange rate

    The value is mathematically rounded to the second decimal place.