--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.com/dev/direct/doc/en/spec.md - https://yandex.com/dev/direct/doc/ru/spec.md - href: en/spec.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt sourcePath: en/reports/spec.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/en/llms.txt # Request: report specification The report parameters are specified in JSON or XML format in the request body. Structure of parameters: {% list tabs %} - JSON ```text translate=no { "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": [( "FCCD" | "LC" | "LSCCD" | "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" ) } } ``` - XML The XML must conform to the XSD schema located at . ```text translate=no (string) (string) ( AdGroupId | ... | Year ) ( EQUALS | ... | STARTS_WITH_IGNORE_CASE ) (string) ... (string) ... ... (string) ... (string) ( FCCD | LC | LSCCD | AUTO ) ... ( FCCD | LC | LSCCD | AUTO ) ( AdGroupId | ... | Year ) ... ( AdGroupId | ... | Year ) (int) ( AdGroupId | ... | Year ) ( ASCENDING | DESCENDING ) ... ... (string) ( ACCOUNT_PERFORMANCE_REPORT | ... | SEARCH_QUERY_PERFORMANCE_REPORT ) ( ALL_TIME | ... | YESTERDAY ) TSV ( YES | NO ) ( YES | NO ) ``` {% endlist %} #| || 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](https://yandex.ru/support/metrica/en/general/goals.html)). 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](https://yandex.com/dev/direct/doc/en/example-metrika.md). | No || || AttributionModels | array of AttributionModelEnum | The attribution models used for calculating data on Yandex Metrica goals (see [Attribution model](https://yandex.ru/support/direct/en/statistics/attribution-model) in Yandex Direct Help). {% note alert "Updates to attribution models in Yandex Direct and Yandex Metrica" %} Active campaigns using legacy models LSC, FC, LYDC, LYDCCD have automatically switched to their closest available cross-device versions or automatic attribution. This model update won't trigger strategy retraining. Methods using deprecated models will automatically upgrade to supported models (LSC to LSCCD, FC to FCCD, LYDC/LYDCCD to AUTO) and return a warning that a different model is in use. {% endnote %} - FCCD — First click (cross-device). - LC — Last click. - LSCCD — Last non-direct click (cross-device). - AUTO — Automatic attribution. The default value is LC. If multiple attribution models are specified, data is output separately for each model. | 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](https://yandex.com/dev/direct/doc/en/fields-list.md) and [Incompatible fields and dependencies](https://yandex.com/dev/direct/doc/en/compatibility.md). 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 each user. 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](https://yandex.ru/dev/direct/doc/en/type). | Yes || || DateRangeType | DateRangeTypeEnum | The period that the report is generated for. See [Report period](https://yandex.ru/dev/direct/doc/en/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 info %} 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. {% endnote %} | When the `DateRangeType` parameter has the value CUSTOM_DATE || || Filter | array of FilterItem | Filters. See [Filtering data](https://yandex.com/dev/direct/doc/en/filters.md). | 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](https://yandex.com/dev/direct/doc/en/fields-list.md) and [Incompatible fields and dependencies](https://yandex.com/dev/direct/doc/en/compatibility.md). | 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 info %} 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. {% endnote %} | 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](https://yandex.com/dev/direct/doc/en/fields-list.md) and [Incompatible fields and dependencies](https://yandex.com/dev/direct/doc/en/compatibility.md). | Yes || || SortOrder | OrderBySortOrderEnum | The sorting direction: - ASCENDING — From lowest to highest. - DESCENDING — From highest to lowest. If omitted, ascending order is used. | No || |#