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 ), ... ],
    "FieldNames": [( "AdGroupId" | ... | "Year" ), ... ],  /* required */
    "Page": { /* Page*/
      "Limit": (int) /* required */
    },
    "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" )  /* required */
  }
}
ParameterTypeDescriptionRequired
ReportDefinition structure
SelectionCriteriaSelectionCriteriaCriteria for selecting data to show in the report.Yes
Goalsarray of string

IDs of Yandex.Metrica goals to get statistics for (see What are goals? Types of goals in the 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 <field>_<goal_id>_<attribution_model> and separate data for each goal.

See also Example: Yandex.Metrica data.

No
AttributionModelsarray of AttributionModelEnumThe attribution models used for calculating data on Yandex.Metrica goals (see Attribution in the Help for Yandex.Direct).

Possible values:

  • FC — First click.
  • LC — Last click.
  • LSC — Last significant (non-direct) click.

The AttributionModels parameter can be set only if the Goals parameter is specified. If the Goals parameter is specified but the AttributionModels parameter is omitted, the LSC value is used by default.

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
FieldNamesarray 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
PagePageRestriction on number of rows in the report. If omitted, the limit is 1,000,000.No
OrderByarray of OrderByNames of fields (columns) to sort the report rows by.No
ReportNamestring

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
ReportTypeReportTypeEnum

Report type. See Report type.

Yes
DateRangeTypeDateRangeTypeEnum

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

Yes
FormatFormatEnumReport format. Currently, only the TSV value is supported.Yes
IncludeVATYesNoEnum

Whether to include VAT in the monetary amounts in the report.

Yes
IncludeDiscountYesNoEnum

Whether to include the discount for monetary amounts in the report.

Yes
SelectionCriteria structure
DateFromstring

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

When the DateRangeType parameter has the value CUSTOM_DATE
DateTostring

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.
Filterarray of FilterItemFilters. See Filtering data.No
FilterItem structure
FieldFieldEnum

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
OperatorFilterOperatorEnum

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
Valuesarray 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
LimitintThe maximum number of rows in the report.Yes
OrderBy structure
FieldFieldEnum

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
SortOrderOrderBySortOrderEnum

The sorting direction:

  • ASCENDING — From lowest to highest.

  • DESCENDING — From highest to lowest.

If omitted, ascending order is used.

No