Request: report specification

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

Structure of parameters:

JSON

XML

{
  "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" | "FCCD" | "LSCCD" | "LYDCCD" | "AUTO" ), ... ],
      "FieldNames": [( "PurchaseRevenue"| "PurchaseProfit" | "PurchaseGoalsRoi" | "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" ) 
  }
}

The XML must conform to the XSD schema located at https://api.direct.yandex.com/v5/reports.xsd.

<?xml version="1.0" encoding="UTF-8"?>
  <ReportDefinition xmlns="http://api.direct.yandex.com/v5/reports">
  <SelectionCriteria>
      <DateFrom>(string)</DateFrom>
      <DateTo>(string)</DateTo>
      <Filter>
      <Field>( AdGroupId | ... | Year )</Field>
      <Operator>( EQUALS | ... | STARTS_WITH_IGNORE_CASE )</Operator>
      <Values>(string)</Values>
          ...
      <Values>(string)</Values>
      </Filter>
      ...
      <Filter> ... </Filter>
  </SelectionCriteria>
  <Goals>(string)</Goals>
      ...
  <Goals>(string)</Goals>
  <AttributionModels>( FC | LC | LSC | LYDC | FCCD | LSCCD | LYDCCD | AUTO )</AttributionModels>
      ...
  <AttributionModels>( FC | LC | LSC | LYDC | FCCD | LSCCD | LYDCCD | AUTO )</AttributionModels>
  <FieldNames>( AdGroupId | ... | Year )</FieldNames>
      ...
  <FieldNames>( AdGroupId | ... | Year )</FieldNames>
  <Page>
      <Limit>(int)</Limit>
  </Page>
  <OrderBy>
      <Field>( AdGroupId | ... | Year )</Field>
      <SortOrder>( ASCENDING | DESCENDING )</SortOrder>
  </OrderBy>
      ...
  <OrderBy> ... </OrderBy>
  <ReportName>(string)</ReportName>
  <ReportType>( ACCOUNT_PERFORMANCE_REPORT | ... | SEARCH_QUERY_PERFORMANCE_REPORT )</ReportType>
  <DateRangeType>( ALL_TIME | ... | YESTERDAY )</DateRangeType>
  <Format>TSV</Format>
  <IncludeVAT>( YES | NO )</IncludeVAT>
  <IncludeDiscount>( YES | NO )</IncludeDiscount>
</ReportDefinition>

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 Yandex Metrica Help). 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	The attribution models used for calculating data on Yandex Metrica goals (see Attribution model in Yandex Direct Help). 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 Yandex Direct cross-device click. AUTO – Automatic attribution. The default value is AUTO. If multiple attribution models are specified, data is output separately for each model. Note 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 Available 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.	When the `DateRangeType` parameter has the value CUSTOM_DATE
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 Available 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 case-insensitive.	Yes
Values	array of string	Values to use for filtering data. Maximum of 10,000 items in the array. All monetary values must 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 Available 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

Was the article helpful?

HTTP headers

Allowed fields