---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.1
alternate:
  - https://yandex.com/dev/metrika/en/stat/openapi/pivot.md
  - https://yandex.com/dev/metrika/ru/stat/openapi/pivot.md
  - href: en/stat/openapi/pivot.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/metrika/en/llms.txt

<div class="openapi">

# Getting a pivot table

<!-- markdownlint-disable-file -->

Enables you to get data broken down by time period (such as by day, week, or month). Use this type of request to build charts and track statistics over time.
 See [an example](https://yandex.com/dev/metrika/en/stat/examples.md#query) with this request.

## Request

<div class="openapi__requests">

<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-get);margin-bottom: 12px">

<div class="openapi__request">

GET {.openapi__method}
```text translate=no
https://api-metrika.yandex.net/stat/v1/data/pivot
```

</div>

</div>

</div>

### Query parameters

#|
|| **Name** | **Description** ||
||

_ids_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: integer[]

Comma-separated list of tag IDs.

_Example:_{.json-schema-reset .json-schema-example} `44147844,2215573`
{.table-cell}
||
||

_metrics_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

List of metrics separated by comma.
Limit: 20 metrics per request.

_Example:_{.json-schema-reset .json-schema-example} `ym:s:pageviews`
{.table-cell}
||
||

_accuracy_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Sample size for the report. Use it to control the [sampling rate](https://yandex.com/dev/metrika/en/stat/sampling.md) (the number of sessions used for calculating results).

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_callback_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Callback function that processes the API response.

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_date1_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Start date of the sample period in YYYY-MM-DD format. You can also use the values: `today`, `yesterday`, `ndaysAgo`.

_Default:_{.json-schema-reset .json-schema-value} `6daysAgo`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_date2_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

End date of the sample period in YYYY-MM-DD format. You can also use the values: `today`, `yesterday`, `ndaysAgo`.

_Default:_{.json-schema-reset .json-schema-value} `today`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_dimensions_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Comma-separated list of dimensions.
Limit: 10 dimensions per request.

_Example:_{.json-schema-reset .json-schema-example} `ym:s:trafficSource`
{.table-cell}
||
||

_direct_client_logins_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string[]

Comma-separated usernames of Yandex Direct clients. Can be used for generating the [Yandex Direct — costs](https://yandex.com/dev/metrika/en/stat/direct-clicks.md) report.

_Example:_{.json-schema-reset .json-schema-example} `login1,login2`
{.table-cell}
||
||

_filters_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

[Segmentation](https://yandex.com/dev/metrika/en/stat/segmentation.md) filter.
Limits: up to 10 unique dimensions and metrics; up to 20 separate filters; up to 10,000 characters per filter row; and up to 100 values per filtering criteria.

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_include_undefined_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

The response will include rows that don't have defined dimension values. This only affects the first dimension. Disabled by default.
{.table-cell}
||
||

_lang_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Language.

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_limit_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Number of items on the results page.
Limit: 100,000.

_Default:_{.json-schema-reset .json-schema-value} `100`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_offset_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Index of the first row of requested data, starting from 1.

_Default:_{.json-schema-reset .json-schema-value} `1`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_pivot_dimensions_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Comma-separated list of dimensions.
 Limit: 10 dimensions per request.

_Example:_{.json-schema-reset .json-schema-example} `ym:s:trafficSource`
{.table-cell}
||
||

_pivot_limit_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Number of columns on the results page.
Limit: 100.

_Default:_{.json-schema-reset .json-schema-value} `5`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_pivot_offset_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Index of the first row of requested data, starting from 1.

_Default:_{.json-schema-reset .json-schema-value} `1`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_preset_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

[Report presets](https://yandex.com/dev/metrika/en/stat/presets.md).

_Example:_{.json-schema-reset .json-schema-example} `sources_summary`
{.table-cell}
||
||

_pretty_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Specifies the formatting for results. To use formatting, set the value to `true`.

_Default:_{.json-schema-reset .json-schema-value} `false`

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_proposed_accuracy_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

If the parameter is set to `true`, the API may automatically increase the accuracy to the recommended level. This can help you get meaningful results when querying small tables containing a very small sample of data.
{.table-cell}
||
||

_sort_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Comma-separated list of dimensions and metrics to use for sorting. By default, data is sorted in descending order (indicated by the `-` symbol in front of the dimension or metric). To sort data in ascending order, remove the `-` symbol.

_Example:_{.json-schema-reset .json-schema-example} ``
{.table-cell}
||
||

_timezone_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Time zone in ±hh:mm format within the range of [-23:59; +23:59] (the plus sign should be denoted as `%2B`).
This time zone is used to calculate the request sample period as well as the date- and time-specific dimensions.
By default, the tag's time zone is used.

_Example:_{.json-schema-reset .json-schema-example} `+03:00`
{.table-cell}
||
|#{.json-schema-properties}

## Responses

<div class="openapi__response__code__200">

## 200 OK

OK

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "query": {
    "timezone": "example",
    "preset": "example",
    "dimensions": [
      "example"
    ],
    "metrics": [
      "example"
    ],
    "sort": [
      "example"
    ],
    "date1": "example",
    "date2": "example",
    "filters": "example",
    "pivot_dimensions": [
      "example"
    ]
  },
  "data": [
    {
      "dimensions": [
        {}
      ],
      "metrics": [
        [
          0.5
        ]
      ]
    }
  ],
  "total_rows": 0,
  "total_rows_rounded": true,
  "sampled": true,
  "contains_sensitive_data": true,
  "sample_share": 0.5,
  "sample_size": 0,
  "sample_space": 0,
  "data_lag": 0,
  "totals": [
    0.5
  ]
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_contains_sensitive_data_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

Indicates whether [sensitive data](https://yandex.com/support/metrica/reports/report-general.html#privacy) can be omitted from the response. Such data includes data calculated by Yandex algorithms: demographic data (gender, age, and other), login page addresses, search phrases, and robot information. If the value is `true`, the response will not display such data if the sample is less than 10 users.
Possible values: `true`, `false`.
{.table-cell}
||
||

_data_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [PivotRow](#entity-PivotRow)[]

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  {
    "dimensions": [
      {}
    ],
    "metrics": [
      [
        0.5
      ]
    ]
  }
]
```

{% endcut %}
{.table-cell}
||
||

_data_lag_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: integer

Delay in updating data, in seconds.
{.table-cell}
||
||

_query_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: [PivotQueryExternal](#entity-PivotQueryExternal)

Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization.

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "timezone": "example",
  "preset": "example",
  "dimensions": [
    "example"
  ],
  "metrics": [
    "example"
  ],
  "sort": [
    "example"
  ],
  "date1": "example",
  "date2": "example",
  "filters": "example",
  "pivot_dimensions": [
    "example"
  ]
}
```

{% endcut %}
{.table-cell}
||
||

_sample_share_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: number

Share of data used for the calculation. Available value ranges from 0 to 1.
{.table-cell}
||
||

_sample_size_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: integer

Number of rows in the data sample.
{.table-cell}
||
||

_sample_space_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: integer

Number of data rows.
{.table-cell}
||
||

_sampled_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

Sampling flag. Indicates whether sampling was applied. Possible values: `true`, `false`.
{.table-cell}
||
||

_total_rows_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: integer

The total number of rows in the response for the entire dataset (after filtering).
{.table-cell}
||
||

_total_rows_rounded_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

Indicates that the total number of rows was rounded.
{.table-cell}
||
||

_totals_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: number[]

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  0.5
]
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

<div class="openapi-entity">

### PivotQueryExternal {#entity-PivotQueryExternal}

Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization.

#|
|| **Name** | **Description** ||
||

_date1_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Start date of the sample period in YYYY-MM-DD format.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_date2_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

End date of the sample period in YYYY-MM-DD format.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_dimensions_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string[]

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  "example"
]
```

{% endcut %}
{.table-cell}
||
||

_filters_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Segmentation filter.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_metrics_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string[]

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  "example"
]
```

{% endcut %}
{.table-cell}
||
||

_pivot_dimensions_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string[]

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  "example"
]
```

{% endcut %}
{.table-cell}
||
||

_preset_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Report preset.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_sort_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string[]

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  "example"
]
```

{% endcut %}
{.table-cell}
||
||

_timezone_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Time zone of the sample period in ±hh:mm format.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "timezone": "example",
  "preset": "example",
  "dimensions": [
    "example"
  ],
  "metrics": [
    "example"
  ],
  "sort": [
    "example"
  ],
  "date1": "example",
  "date2": "example",
  "filters": "example",
  "pivot_dimensions": [
    "example"
  ]
}
```

{% endcut %}

</div>

<div class="openapi-entity">

### PivotRow {#entity-PivotRow}

Response rows. An array in which each item is a single row of the result.

#|
|| **Name** | **Description** ||
||

_dimensions_{.json-schema-reset .json-schema-property}
{.table-cell}|
{% cut "**Type**: object[]" %}

#|
||

_[additional]_{.json-schema-reset .json-schema-additional-property}
{.table-cell}|
**Type**: string

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
|#{.json-schema-properties}

{% endcut %}

Array of dimension values for this row. Each dimension value is an object. It must have the `name` field, which is a text value. But it can also have additional fields, such as `id`.

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  {}
]
```

{% endcut %}
{.table-cell}
||
||

_metrics_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: number[][]

Array of arrays of metric values for this row. The outer array lists metrics, whereas the inner arrays list values of a specific metric for each time group.

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
[
  [
    0.5
  ]
]
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "dimensions": [
    {}
  ],
  "metrics": [
    [
      0.5
    ]
  ]
}
```

{% endcut %}

</div>

</div>

</div>

[*Deprecated]: No longer supported, please use an alternative and newer version.