Request: report specification

The report parameters are specified in JSON or XML format in the request body.

Structure of parameters:

{
  "params" : { /* ReportDefinition */
    "SelectionCriteria": { /* SelectionCriteria */
      "DateFrom": (string),
      "DateTo": (string),
      "Filter": [{ /* FilterItem*/
        "Field": ( "AdGroupId" | ... | "Year" ),  /* required */
        "Operator": ( "EQUALS" | ... | "STARTS_WITH_IGNORE_CASE" ), /* required */
        "Values": [(string), ... ] /* required */
      }, ... ]
    }, /* required */
    "Goals": [(string), ... ],
    "AttributionModels": [( "FC" | "LC" | "LSC" | "LYDC" ), ... ],
    "FieldNames": [( "AdGroupId" | ... | "Year" ), ... ],  /* required */
    "Page": { /* Page*/
      "Limit": (int) /* required */
      "Offset": (int)
    }
    "OrderBy": [{ /* OrderBy*/
      "Field": ( "AdGroupId" | ... | "Year" ),  /* required */
      "SortOrder": ( "ASCENDING" | "DESCENDING" )
    }, ... ],
    "ReportName": (string),  /* required */
    "ReportType": ( "ACCOUNT_PERFORMANCE_REPORT" | ... | "SEARCH_QUERY_PERFORMANCE_REPORT" ),  /* required */
    "DateRangeType": ( "ALL_TIME" | ... | "YESTERDAY" ),  /* required */
    "Format": ( "TSV" ),  /* required */
    "IncludeVAT": ( "YES" | "NO" ),  /* required */
    "IncludeDiscount": ( "YES" | "NO" ) 
  }
}
Parameter Type Description Required
ReportDefinition structure
SelectionCriteria SelectionCriteria Criteria for selecting data to show in the report. Yes
Goals array of string

IDs of Yandex Metrica goals to get statistics for (see What are goals? Types of goals in Help for Yandex Metrica). Maximum of 10 items in the array.

If this parameter is specified, instead of the ConversionRate, Conversions, CostPerConversion, GoalsRoi and Revenue fields with aggregated data for all goals, the report will show the same fields with names in the format and separate data for each goal.

See also Example: Yandex Metrica data.

No
AttributionModels array of AttributionModelEnum Attribution models used for calculating data on Yandex Metrica goals (see Attribution in Help for Yandex Direct).

Possible values:

  • FC — First click.
  • LC — Last click.
  • LSC — Last significant (non-direct) click.
  • LYDC — Last click from Yandex Direct.
  • FCCD – First cross-device click.
  • LSCCD – Last significant (non-direct) cross-device click.
  • LYDCCD – Last cross-device click from Yandex Direct.
  • AUTO – Automatic attribution.

The default value is AUTO.

If multiple attribution models are specified, data is output separately for each model.

Attention.

When using the LSC and FC attribution models, the session date is not the date the site was actually visited, but the date of the click that was the source of the session. This means that a session and its data (page depth, conversion, revenue, etc.) are reflected in the report if the date of the click falls within the report period.

If you generate the report again for the same period with the same parameters, the Yandex.Metrica data in the report may change if there have been sessions since the last time the report was created that came from clicks made during the report period.

No
FieldNames array of FieldEnum

Names of fields (columns) that will be in the report.

To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies.

For the REACH_AND_FREQUENCY_PERFORMANCE_REPORT report type, the CampaignId field is required.

Yes
Page Page Restriction on number of rows in the report. If omitted, the limit is 1,000,000. No
OrderBy array of OrderBy Names of fields (columns) to sort the report rows by. No
ReportName string

Name of the report. Shown in the first row in the report.

In offline mode, the report name must be unique for the advertiser. If a report with the same name but different parameters has already been generated or is in the queue, an error is returned.

Yes
ReportType ReportTypeEnum

Report type. See Report type.

Yes
DateRangeType DateRangeTypeEnum

The period that the report is generated for. See Report period.

Yes
Format FormatEnum Report format. Currently, only the TSV value is supported. Yes
IncludeVAT YesNoEnum Whether to include VAT in the monetary amounts in the report. Yes
IncludeDiscount YesNoEnum Whether to include the discount for monetary amounts in the report.

This parameter is deprecated because the discount is no longer available in Yandex Direct as of September 1, 2015.

No
SelectionCriteria structure
DateFrom string

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

When the DateRangeType parameter has the value CUSTOM_DATE
DateTo string

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

Note. The DateFrom and DateTo parameters are required when the DateRangeType parameter is set to CUSTOM_DATE. They are not allowed when other values are set.
Filter array of FilterItem Filters. See Filtering data. No
FilterItem structure
Field FieldEnum

The name of the field used for filtering data. Each field can only be used in one filter. Multiple filters with the same field are not allowed.

To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies.

Yes
Operator FilterOperatorEnum

The operator to use for filtering data:

  • EQUALS — The field value is equal to the value from Values.

  • NOT_EQUALS — The field value is not equal to the value from Values.

  • IN — The field value is equal to any value from Values.

  • NOT_IN — The field value is not equal to any of the values from Values.

  • LESS_THAN — The field value is less than the value from Values.

  • GREATER_THAN — The field value is greater than the value from Values.

  • STARTS_WITH_IGNORE_CASE — The field value starts with the value from Values.

  • DOES_NOT_START_WITH_IGNORE_CASE — The field value does not start with the value from Values.

  • STARTS_WITH_ANY_IGNORE_CASE — The field value starts with any of the values specified in Values.

  • DOES_NOT_START_WITH_ALL_IGNORE_CASE — The field value does not start with any of the values specified in Values.

Note.

The EQUALS, NOT_EQUALS, IN, and NOT_IN operators are not case-sensitive for the Keyword and Query fields. For the other fields, they are case-sensitive.

The STARTS_WITH_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, and DOES_NOT_START_WITH_ALL_IGNORE_CASE operators are not case-sensitive.

Yes
Values array of string

Values to use for filtering data. Maximum of 10,000 items in the array.

All monetary values should be specified as integers: the amount in the currency, multiplied by 1,000,000 (regardless of the .returnMoneyInMicros: false header).

Yes
Page structure
Limit int The maximum number of rows in the report. Yes
Offset int Number of rows to skip when getting the selection. No
OrderBy structure
Field FieldEnum

The name of the field used for sorting rows.

To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies.

Yes
SortOrder OrderBySortOrderEnum

The sorting direction:

  • ASCENDING — From lowest to highest.

  • DESCENDING — From highest to lowest.

If omitted, ascending order is used.

No
Parameter Type Description Required
ReportDefinition structure
SelectionCriteria SelectionCriteria Criteria for selecting data to show in the report. Yes
Goals array of string

IDs of Yandex Metrica goals to get statistics for (see What are goals? Types of goals in Help for Yandex Metrica). Maximum of 10 items in the array.

If this parameter is specified, instead of the ConversionRate, Conversions, CostPerConversion, GoalsRoi and Revenue fields with aggregated data for all goals, the report will show the same fields with names in the format and separate data for each goal.

See also Example: Yandex Metrica data.

No
AttributionModels array of AttributionModelEnum Attribution models used for calculating data on Yandex Metrica goals (see Attribution in Help for Yandex Direct).

Possible values:

  • FC — First click.
  • LC — Last click.
  • LSC — Last significant (non-direct) click.
  • LYDC — Last click from Yandex Direct.
  • FCCD – First cross-device click.
  • LSCCD – Last significant (non-direct) cross-device click.
  • LYDCCD – Last cross-device click from Yandex Direct.
  • AUTO – Automatic attribution.

The default value is AUTO.

If multiple attribution models are specified, data is output separately for each model.

Attention.

When using the LSC and FC attribution models, the session date is not the date the site was actually visited, but the date of the click that was the source of the session. This means that a session and its data (page depth, conversion, revenue, etc.) are reflected in the report if the date of the click falls within the report period.

If you generate the report again for the same period with the same parameters, the Yandex.Metrica data in the report may change if there have been sessions since the last time the report was created that came from clicks made during the report period.

No
FieldNames array of FieldEnum

Names of fields (columns) that will be in the report.

To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies.

For the REACH_AND_FREQUENCY_PERFORMANCE_REPORT report type, the CampaignId field is required.

Yes
Page Page Restriction on number of rows in the report. If omitted, the limit is 1,000,000. No
OrderBy array of OrderBy Names of fields (columns) to sort the report rows by. No
ReportName string

Name of the report. Shown in the first row in the report.

In offline mode, the report name must be unique for the advertiser. If a report with the same name but different parameters has already been generated or is in the queue, an error is returned.

Yes
ReportType ReportTypeEnum

Report type. See Report type.

Yes
DateRangeType DateRangeTypeEnum

The period that the report is generated for. See Report period.

Yes
Format FormatEnum Report format. Currently, only the TSV value is supported. Yes
IncludeVAT YesNoEnum Whether to include VAT in the monetary amounts in the report. Yes
IncludeDiscount YesNoEnum Whether to include the discount for monetary amounts in the report.

This parameter is deprecated because the discount is no longer available in Yandex Direct as of September 1, 2015.

No
SelectionCriteria structure
DateFrom string

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

When the DateRangeType parameter has the value CUSTOM_DATE
DateTo string

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

Note. The DateFrom and DateTo parameters are required when the DateRangeType parameter is set to CUSTOM_DATE. They are not allowed when other values are set.
Filter array of FilterItem Filters. See Filtering data. No
FilterItem structure
Field FieldEnum

The name of the field used for filtering data. Each field can only be used in one filter. Multiple filters with the same field are not allowed.

To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies.

Yes
Operator FilterOperatorEnum

The operator to use for filtering data:

  • EQUALS — The field value is equal to the value from Values.

  • NOT_EQUALS — The field value is not equal to the value from Values.

  • IN — The field value is equal to any value from Values.

  • NOT_IN — The field value is not equal to any of the values from Values.

  • LESS_THAN — The field value is less than the value from Values.

  • GREATER_THAN — The field value is greater than the value from Values.

  • STARTS_WITH_IGNORE_CASE — The field value starts with the value from Values.

  • DOES_NOT_START_WITH_IGNORE_CASE — The field value does not start with the value from Values.

  • STARTS_WITH_ANY_IGNORE_CASE — The field value starts with any of the values specified in Values.

  • DOES_NOT_START_WITH_ALL_IGNORE_CASE — The field value does not start with any of the values specified in Values.

Note.

The EQUALS, NOT_EQUALS, IN, and NOT_IN operators are not case-sensitive for the Keyword and Query fields. For the other fields, they are case-sensitive.

The STARTS_WITH_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, and DOES_NOT_START_WITH_ALL_IGNORE_CASE operators are not case-sensitive.

Yes
Values array of string

Values to use for filtering data. Maximum of 10,000 items in the array.

All monetary values should be specified as integers: the amount in the currency, multiplied by 1,000,000 (regardless of the .returnMoneyInMicros: false header).

Yes
Page structure
Limit int The maximum number of rows in the report. Yes
Offset int Number of rows to skip when getting the selection. No
OrderBy structure
Field FieldEnum

The name of the field used for sorting rows.

To see which fields you can specify, see the sections Allowed fields and Incompatible fields and dependencies.

Yes
SortOrder OrderBySortOrderEnum

The sorting direction:

  • ASCENDING — From lowest to highest.

  • DESCENDING — From highest to lowest.

If omitted, ascending order is used.

No