---
metadata:
  - name: generator
    content: Diplodoc Platform v5.46.1
alternate:
  - https://yandex.com/dev/partner-statistics/doc/en/reference/report.md
  - https://yandex.com/dev/partner-statistics/doc/ru/reference/report.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/partner-statistics/doc/en/llms.txt

# How to build a report

To build a report:

## Request the statistics tree {#request-tree}

To get the statistics tree, use the [Statistics tree](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-tree2.md) resource. As a result, you get the statistics levels and the fields for each level.

Sample request:
```no-highlight
curl -i -X GET 'https://partner.yandex.ru/api/statistics2/tree.json?lang=ru&pretty=1' \
-H 'Authorization: OAuth 123qwe456a...'
```

Example of part of a response:
```json
{
   "data" : {
      "tree" : [
         {
            "conflict_fields" : [],
            "dimension_fields" : [
               {
                  "id" : "date",
                  "title" : "Date",
                  "type" : "select",
                  "values" : [
                     [
                        "month",
                        "by month"
                     ],
                     [
                        "week",
                        "by week"
                     ],
                     [
                        "day",
                        "by day"
                     ],
                     [
                        "year",
                        "by year"
                     ]
                  ]
               },
               {
                  "id" : "geo",
                  "title" : "Geography",
                  "type" : "select",
                  "values" : [
                     [
                        "country",
                        "by country"
                     ],
                     [
                        "city",
                        "by city"
                     ],
                     [
                        "area",
                        "by region"
                     ]
                  ]
               }
            ],
            "entity_fields" : [
               {
                  "category" : 14,
                  "category_name" : "Product",
                  "id" : "block_level",
                  "index" : 4,
                  "label" : "Product's ad unit level",
                  "type" : "tree"
               },
               {
                  "category" : 14,
                  "category_name" : "Product",
                  "id" : "page_level",
                  "index" : 5,
                  "label" : "Product level",
                  "type" : "tree"
               },
               {
                  "category" : 12,
                  "category_name" : "Platform",
                  "id" : "page_id",
                  "index" : 11,
                  "label" : "Page ID",
                  "type" : "publicid"
               },
               {
                  "category" : 12,
                  "category_name" : "Platform",
                  "id" : "page_caption",
                  "index" : 12,
                  "label" : "Page name",
                  "type" : "text"
               },
               {
                  "category" : 10,
                  "category_name" : "Ad unit",
                  "id" : "complex_block_id",
                  "index" : 14,
                  "label" : "Ad unit ID",
                  "type" : "publicid"
               },
               {
                  "category" : 10,
                  "category_name" : "Ad unit",
                  "id" : "block_caption",
                  "index" : 15,
                  "label" : "Ad unit name",
                  "type" : "text"
               },
               {
                  "category" : 10,
                  "category_name" : "Ad unit",
                  "id" : "tag_id",
                  "index" : 16,
                  "label" : "Cross section ID",
                  "type" : "publicid"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "adfox_block",
                  "index" : 17,
                  "label" : "ADFOX unit",
                  "type" : "boolean"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "deal_id",
                  "index" : 18,
                  "label" : "Transaction ID",
                  "type" : "publicid"
               },
               {
                  "category" : 9,
                  "category_name" : "ADFOX",
                  "id" : "deal_caption",
                  "index" : 19,
                  "label" : "Transaction name",
                  "type" : "text"
               },
               {
                  "id" : "business_rule_id",
                  "index" : 20,
                  "label" : "Rule ID",
                  "type" : "publicid"
               },
               {
                  "id" : "business_rule_title",
                  "index" : 21,
                  "label" : "Rule name",
                  "type" : "text"
               },
               {
                  "category" : 7,
                  "category_name" : "Traffic",
                  "id" : "os",
                  "index" : 22,
                  "label" : "Operating system",
                  "type" : "publicid"
               },
               {
                  "category" : 7,
                  "category_name" : "Traffic",
                  "id" : "browser",
                  "index" : 23,
                  "label" : "Browser",
                  "type" : "publicid"
               },
...
               {
                  "category" : 6,
                  "category_name" : "Recommendation metrics",
                  "id" : "RecommendationWidgetCTR",
                  "index" : 58,
                  "title" : "Recommendation widget CTR",
                  "type" : "text"
               }
            ],
            "has_product" : "",
            "has_raw_stat" : "",
            "id" : "payment",
            "title" : "Revenue"
         }
      ]
   },
   "result" : "ok"
}
```


## Choose fields from the statistics tree for building the report {#fields}

Fields can be divided into three groups:


- [Indicator fields](#values)
- [Dimension fields](#groups)
- [Filter fields](#filters)


### Indicator fields {#values}

These are fields that output some statistical information, such as ad impressions in blocks or ad requests in blocks.

{% cut "Mandatory" %}

The report must have at least one field from this group.

{% endcut %}

{% cut "Where to find the list of fields" %}

To get the list of available fields, see the `fields` structure for the [Statistics tree](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-tree2.md) resource. 
Example:
```json
{
  ...
  "fields":
  [
    {
      "category" : 1,
      "category_name" : "Source data",
      "id" : "shows",
      "index" : 30,
      "title" : "Impressions in ad units",
      "type" : "text"
    },
    {
      "category" : 1,
      "category_name" : "Source data",
      "id" : "hits",
      "index" : 36,
      "title" : "Ad requests in ad units",
      "type" : "text"
    }
  ]
  ...
}
```

{% endcut %}

{% cut "Add to the report" %}

Add fields as values of the `field` parameter for the [Report on statistics level](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-get2.md) resource. Use the IDs of the chosen fields to add them.

<!-- source: en/_includes/reference/statistics-get2/id-statistics-get2/note-field.md -->
{% note info %}

To add multiple fields to the report, specify the parameter multiple times:
```no-highlight
field=shows&field=hits
```

{% endnote %}
<!-- endsource: en/_includes/reference/statistics-get2/id-statistics-get2/note-field.md -->

{% endcut %}




### Dimension fields {#groups}

These are fields that can be used for grouping the rest of the data in the report.

There are two types of dimensions:
- Grouping by fields that do not belong to a particular product at the current level (for example, grouping by a period, currency or field from another product).
- Grouping by the other fields, such as IDs and names.

{% cut "Mandatory" %}

Dimension fields can be omitted from the report.


{% endcut %}

{% cut "Where to find the list of fields" %}

To get the list of available fields for grouping, see the `dimension_fields` and `entity_fields` structures for the [Statistics tree](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-tree2.md) resource.

Example:
```json
...
  "dimension_fields":
  [
    {
      "id" : "date",
      "title" : "Period",
      "type" : "select",
      "values" : [
        [
          "day",
          "Grouping by days"
        ],
        [
          "week",
          "Grouping by weeks"
        ],
        [
          "month",
          "Grouping by months"
        ],
        [
          "year",
          "Grouping by years"
        ]
      ]
    }, 
    {
      "filter_values" : [
        {
          "id" : "3",
          "key" : "id3",
          "label" : "EUR"
        },
        {
          "id" : "2",
          "key" : "id2",
          "label" : "RUB"
        },
        {
          "id" : "1",
          "key" : "id1",
          "label" : "USD"
        }
      ],
      "id" : "currency_id",
      "title" : "Currency",
      "type" : "dictionary"
    },
    {
      ...
    }
  ]
...
```

```json
...
  "entity_fields":
  [
    {
      "id" : "page_id",
      "label" : "Page ID",
      "type" : "page_id"
    },
    {
      "id" : "domain",
      "label" : "Domain",
      "type" : "text"
    }
  ]
...
```

{% endcut %}

{% cut "Add to the report" %}

Add fields as values of the `dimension_field` and `entity_field` parameters for the [Report on statistics level](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-get2.md) resource.

<!-- source: en/_includes/reference/statistics-get2/id-statistics-get2/note-entity_field.md -->
{% note info %}

To group by multiple fields, specify the field IDs as follows:
```no-highlight
entity_field=domain&entity_field=page_id
```

{% endnote %}
<!-- endsource: en/_includes/reference/statistics-get2/id-statistics-get2/note-entity_field.md -->


{% endcut %}

### Filter fields {#filters}

Use these fields for filtering data. Filtering is applied during report generation.

SQL operators are applied to the fields, and the report is built based on the input conditions.

{% cut "Mandatory" %}

Filter fields can be omitted in a report.

{% endcut %}

{% cut "Where to find the list of fields" %}

To get the list of available fields for filtering data when generating the report, see the `entity_filter_fields` structure for the [Statistics tree](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-tree2.md) resource. 
Example:
```json
...
  "entity_filter_fields":
  {
    "multistate" : 
    {
      "label" : "Status",
      "type" : "multistate",
      "values" : 
      {
        "need_approve" : "Needs approval",
        "rejected" : "Rejected by moderator",
        "stopped" : "Stopped",
        "testing" : "Testing",
        "working" : "Working"
      }
    },
    "page_id" :
   {
     "label" : "Page ID",
     "type" : "number"
   }
...
```

{% endcut %}

{% cut "Add to the report" %}

Add fields as string values of the `filter` parameter for the [Report on statistics level](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-get2.md) resource.

{% endcut %}

There are restrictions on using SQL operators. These restrictions are related to the data types that are used in fields:

{% cut "= (equal to)" %}

Used for scalar values.

#### Meaning
Generates a report for the specified field value.
#### This operator works with the following types of fields:

- `boolean`
- `contractnumber`
- `dictionary`
- `domain_mirror`
- `login`
- `multistate`
- `number`
- `publicid`
- `straight_number`
- `text`
- `tree`

#### Example
You need to filter data by content sites that have the status “Working”:
```no-highlight
filter=["multistate","=","working"]
```
where `multistate` is the field name and `working` is the field value.
#### Result
The report shows the requested data, filtered by working content sites.

{% endcut %}

{% cut "<> (not equal to)" %}

Used for scalar values.

#### Meaning
The specified field value is excluded from the report.
#### This operator works with the following types of fields:

- `dictionary`
- `domain_mirror`
- `login`
- `multistate`
- `number`
- `publicid`
- `straight_number`
- `text`
- `tree`

#### Example
You need to filter data by content sites, excluding sites that have the status “Working”:
```no-highlight
filter=["multistate","<>","working"]
```
where `multistate` is the field name and `working` is the field value.
#### Result
The report shows the requested data, filtered by sites' working status. Data for working sites will be excluded from the report.

{% endcut %}



{% cut "IN (included in)" %}

Used for arrays.

#### Meaning
Generates a report for the specified values of the field.
#### This operator works with the following types of fields:

- `contractnumber`
- `domain_mirror`
- `login`
- `number`
- `publicid`
- `straight_number`
- `text`

#### Example
You need to filter data by the IDs of content sites that are included in the specified list:
```no-highlight
filter=["page_id","IN",["53100","53101"]]
```
where `page_id` is the field name, and `53100, 53101` are the field values.
#### Result
The report shows the requested data, filtered by the site IDs from the list.

{% endcut %}



{% cut "> (greater than)" %}

Used for scalar values.

#### Meaning
Generates a report for field values that are greater than the one specified.
#### This operator works with the following types of fields:

- `number`
- `straight_number`

#### Example
You need to filter data by content sites with IDs that are greater than the specified value:
```no-highlight
filter=["page_id",">","53100"]
```
where `page_id` is the field name and `53100` is the field value.
#### Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be greater than the specified value.

{% endcut %}



{% cut "< (less than)" %}

Used for scalar values.

#### Meaning
Generates a report for field values that are less than the one specified.
#### This operator works with the following types of fields:

- `number`
- `straight_number`

#### Example
You need to filter data by the IDs of content sites that are less than the specified value:
```no-highlight
filter=["page_id","<","53100"]
```
where `page_id` is the field name and `53100` is the field value.
#### Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be less than the specified value.

{% endcut %}


{% cut ">= (greater than or equal to)" %}

Used for scalar values.

#### Meaning
Creates a report on the field values that are greater than or equal to the specified value.
#### This operator works with the following types of fields:

- `number`
- `straight_number`

#### Example
You need to filter data by content sites with IDs that are greater than or equal to the specified value:
```no-highlight
filter=["page_id",">=","53100"]
```
where `page_id` is the field name and `53100` is the field value.
#### Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be greater than or equal to the specified value.

{% endcut %}

{% cut "<= (less than or equal to)" %}

Used for scalar values.

#### Meaning
Creates a report on the field values that are less than or equal to the specified value.
#### This operator works with the following types of fields:

- `number`
- `straight_number`

#### Example
You need to filter data by the IDs of content sites that are less than or equal to the specified value:
```no-highlight
filter=["page_id","<=","53100"]
```
where `page_id` is the field name and `53100` is the field value.
#### Result
The report shows the requested data, filtered by all the site IDs. The site IDs will be less than or equal to the specified value.

{% endcut %}

{% cut "NOT IN" operator (not included in)" %}

Used for arrays.

#### Meaning
Creates a report on the field values that are not included in the specified list.
#### This operator works with the following types of fields:

- `domain_mirror`
- `login`
- `number`
- `publicid`
- `straight_number`
- `text`

#### Example
You need to filter data by the IDs of content sites that are not included in the specified list:
```no-highlight
filter=["page_id","NOT IN",["53100","53101"]]
```
where `page_id` is the field name, and `53100, 53101` are the field values.
#### Result
The report shows the requested data, filtered by all the site IDs. Data for the specified site IDs will be omitted from the report.

{% endcut %}



{% cut ""LIKE" operator (included in the specified substring)" %}

Used for scalar values.

#### Meaning
Creates a report on the field values that are included in the specified substring.
#### This operator works with the following types of fields:

- `domain_mirror`
- `login`
- `text`

#### Example
You need to filter data by the name of a site that is included in the specified value:
```no-highlight
filter=["domain","LIKE","aliexpress"]
```
where `domain` is the field name, and `aliexpress` is the field value.
#### Result
The report shows the requested data, filtered by the names of sites that are included in the specified value.

{% endcut %}

{% cut "NOT LIKE (not included in the specified substring)" %}

Used for scalar values.

#### Meaning
Creates a report on the field values that are not included in the specified substring.
#### This operator works with the following types of fields:

- `domain_mirror`
- `login`
- `text`

#### Example
You need to filter data by a website name that is not included in the specified value:
```no-highlight
filter=["domain","NOT LIKE","aliexpress"]
```
where `domain` is the field name, and `aliexpress` is the field value.
#### Result
The report shows the requested data, filtered by site names. Data for the specified site name will be omitted from the report.

{% endcut %}

{% cut ""AND" operator (and)" %}

#### Meaning
Used for combining filters.
#### Example
You need to filter data by the site name and by the content site ID. You have two filters:
```no-highlight
filter=["domain","=","aliexpress"]
```

```no-highlight
filter=["page_id","=","53100"]
```
You combine the two filters into one:
```no-highlight
filter=["AND",[["domain","=","aliexpress"],["page_id","=","53100"]]]
```

#### Result
The report shows the requested data, filtered by the site name and by the content site ID.

{% endcut %}



{% cut ""OR" (logical or)" %}

#### Meaning
Used for performing at least one of the listed filters.
#### Example
You need to filter data by the site name or by the content site ID. You have two filters:
```no-highlight
filter=["domain","=","aliexpress"]
```

```no-highlight
filter=["page_id","=","53100"]
```
You combine the two filters into one:
```no-highlight
filter=["OR",[["domain","=","aliexpress"],["page_id","=","53100"]]]
```

#### Result
The report shows the requested data, filtered by the site name or by the content site ID.

{% endcut %}








## Form a request for building the report {#request-report}

Choose fields for building the report. As an example, we'll choose these fields:

- Indicator fields. We'll output data for the following indicators: ad requests in ad units (`hits`), ads rendered in ad units (`hits_render`), and impressions in ad units (`shows`).
- Dimension fields. We'll group data by the following fields: period by day (`period|day`), and the ad platform ID (`page_id`).
- Filter fields. We'll filter data by the ad platform with the ID 458472 (`"page_id","=","458472"`).

The request syntax is described in the [Statistics report](https://yandex.com/dev/partner-statistics/doc/en/reference/statistics-get2.md) resource. We'll generate a report with the following parameters:
1. Choosing the response language

    
    
1. Setting the time interval to get the report for
    ```no-highlight
    period=thismonth
    ```
    
1. Formatting the response for readability
    ```no-highlight
    pretty=1
    ```
    
1. Passing the indicator fields that we want to see in the report
    ```no-highlight
    field=shows&field=hits_render&field=hits
    ```
    
1. Grouping data in the report by day
    ```no-highlight
    dimension_field=date|day
    ```
    
1. Grouping data by ad platform
    ```no-highlight
    entity_field=page_id
    ```
    
1. Filtering data by the site and getting a report that only contains data for the specified ad platform
    ```no-highlight
    filter=["page_id","=","458472"]'
    ```

Final request:
```no-highlight
curl -g -X GET 'https://partner.yandex.ru/api/statistics2/get.json? \
lang=ru&pretty=1 \
&dimension_field=date|day \
&period=thismonth \
&entity_field=page_id \
&field=shows \
&field=hits_render \
&field=hits \
&filter=["page_id","=","458472"]' \
-H 'Authorization: OAuth 123qwe456a...'
```

Response fragment: 
```json
{
   "data" : {
      "currencies" : [
         {
            "code" : "USD",
            "id" : "1"
         },
         {
            "code" : "RUB",
            "id" : "2"
         },
         {
            "code" : "EUR",
            "id" : "3"
         }
      ],
      "dimensions" : {
         "date" : {
            "index" : 1,
            "title" : "Date",
            "type" : "date"
         },
         "page_id" : {
            "index" : 2,
            "title" : "Page ID",
            "type" : "page_id"
         }
      },
      "is_last_page" : true,
      "measures" : {
         "hits" : {
            "index" : 5,
            "title" : "Ad requests in ad units",
            "type" : "number",
            "unit" : "count"
         },
         "hits_render" : {
            "index" : 4,
            "title" : "Ads rendered in ad units",
            "type" : "number",
            "unit" : "count"
         },
         "shows" : {
            "index" : 3,
            "title" : "Impressions in ad units",
            "type" : "number",
            "unit" : "count"
         }
      },
      "periods" : [
         [
            "2020-12-01",
            "2020-12-15"
         ]
      ],
      "points" : [
         {
            "dimensions" : {
               "date" : [
                  "2020-12-02"
               ],
               "page_id" : 458472
            },
            "measures" : [
               {
                  "hits" : 0,
                  "hits_render" : 0,
                  "shows" : 0
               }
            ]
         },
         {
            "dimensions" : {
               "date" : [
                  "2020-12-14"
               ],
               "page_id" : 458472
            },
            "measures" : [
               {
                  "hits" : 0,
                  "hits_render" : 0,
                  "shows" : 0
               }
            ]
         },
         {
            "dimensions" : {
               "date" : [
                  "2020-12-11"
               ],
               "page_id" : 458472
            },
            "measures" : [
               {
                  "hits" : 254,
                  "hits_render" : 254,
                  "shows" : 43
               }
            ]
         },
         {
            "dimensions" : {
               "date" : [
                  "2020-12-15"
               ],
               "page_id" : 458472
            },
            "measures" : [
               {
                  "hits" : 0,
                  "hits_render" : 0,
                  "shows" : 0
               }
            ]
         },
         {
            "dimensions" : {
               "date" : [
                  "2020-12-08"
               ],
               "page_id" : 458472
            },
            "measures" : [
               {
                  "hits" : 0,
                  "hits_render" : 0,
                  "shows" : 0
               }
            ]
         }
      ],
      "report_title" : "Report for the period from 01.12.2020 to 15.12.2020",
      "total_rows" : 5,
      "totals" : {
         "2" : [
            {
               "hits" : 254,
               "hits_render" : 254,
               "shows" : 43
            }
         ]
      }
   },
   "result" : "ok"
}
```