Drill down


Access tokens will not be accepted in URL parameters starting February 13, 2019. To continue working with the Yandex.Metrica API, set up authorization by passing the token in the HTTP header.

The outdated authorization method will be temporarily disabled on January 23, January 30, and February 6 for maintenance. Authorization using URL parameters will be unavailable on these dates.

Allows you to generate a multi-level (tree) report. In this case, each level corresponds to one dimension.

A request to drilldown method returns one sublevel for the specified parent level. Parent level is specified in the parameter parent_id. To get data for the first level, send a request without the parent_id parameter.

To get data for nested levels, you must specify the path from the root. The route is generated from the values of the field id of parameter dimension. If the id field is missing, specify the name field.

See how uses this request in the example.

  1. Request syntax
  2. Response format

Request syntax

 ? [direct_client_logins=<string,_string,...>]
 & [ids=<int,int,...>]
 & [metrics=<string>]
 & [accuracy=<string>]
 & [callback=<string>]
 & [date1=<string>]
 & [date2=<string>]
 & [dimensions=<string>]
 & [filters=<string>]
 & [id=<integer>]
 & [include_undefined=<boolean>]
 & [lang=<string>]
 & [limit=<int>]
 & [offset=<int>]
 & [only_expandable_undefined=<boolean>]
 & [parent_id=<list>]
 & [preset=<string>]
 & [pretty=<boolean>]
 & [proposed_accuracy=<boolean>]
 & [sort=<string>]
 & [timezone=<string>]
Query parameters
direct_client_loginsComma-separated logins of Yandex.Direct clients. Used for generating the Yandex.Direct - costs report.
idsCounter IDs, separated by commas. Used instead of id parameter.

List of metrics, separated by commas.

Limit: 20 metrics in request.

accuracyAccuracy of the result. Use it to control the sampling rate (the number of sessions used for calculating results).

Default value: medium

callbackCallback function which returns an API response.

Start date of requesting data period in the format YYYY-MM-DD. Also use values: today, yesterday, ndaysAgo.

Default value: 6daysAgo


End date of requesting data period in the format YYYY-MM-DD. Also uses values: today, yesterday, ndaysAgo.

Default value: today


List of dimensions, separated by commas.

Limit: 10 dimensions in request.


Segmentation filter.

Limit: number of unique dimensions and metrics — up to 10, number of separate filters — up to 20, row length in filter — up to 10 000 characters.

idCounter ID. Outdated, use ids.
include_undefinedEnabled in response row, for which values of dimensions are not defined. This only affects the first dimension. Disabled by default.

Number of elements on results page.

Limit: 100,000.

Default value: 100

offsetIndex of first row of requesting data, beginning with 1.

Default value: 1

only_expandable_undefinedDeletes unexpanded undefined values from results. Only use when include_undefined=true.
parent_idChoice of rows for further expansion. Consists of json key lists.

Default value: []

prettySpecifies the formatting of results. To use formatting, enter the value true.

Default value: false

proposed_accuracyIf parameter is set to true, the API has the right to automatically increase accuracy to the recommended value. This parameter can help you obtain meaningful results when a request is sent to a small table with very small sampling.
sortA list of dimensions and metrics separated by comma, which are sorted. By default it 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.

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

Response format

    "total_rows" :  < long > ,
    "total_rows_rounded" :  < boolean > ,
    "sampled" :  < boolean > ,
    "sample_share" :  < double > ,
    "sample_size" :  < long > ,
    "sample_space" :  < long > ,
    "data_lag" :  < int > ,
    "query" : {
        "ids" : [  < int > , ... ],
        "timezone" :  < string > ,
        "preset" :  < string > ,
        "dimensions" : [  < string > , ... ],
        "metrics" : [  < string > , ... ],
        "sort" : [  < string > , ... ],
        "date1" :  < string > ,
        "date2" :  < string > ,
        "filters" :  < string > ,
        "limit" :  < integer > ,
        "offset" :  < integer > 
    "totals" : [  < double > , ... ],
    "min" : [  < double > , ... ],
    "max" : [  < double > , ... ],
    "data" : [ {
        "dimension" : {
            "key_1" :  < string > ,
            "key_2" : ...
        "metrics" : [  < double > , ... ],
        "expand" :  < boolean > 
    }, ... ]
Parameters Description
total_rows The total number of rows in the response for the entire data set (after filtering).
total_rows_rounded Sign that the total number of rows was rounded.
sampled Indication of sampling. Shows whether sampling was applied. Possible values: true, false.
sample_share Share of processed data, for which a calculation was carried out. Available values range from 0 to 1.
sample_size Number of rows in requesting data.
sample_space Number of rows of data.
data_lag Delay in updating data, in seconds.
query Original request. Contains request parameters, including detailed parameters from template and parameters for parametrization attributes scheme.
totals Total results for metrics across all data (taking into account filter).
min Minimum results for metrics among keys caught in search results.
max Maximum results for metrics among keys caught in search results.
data Rows of response. Is an array, each element of which is one row of a result.
ids IDs of counters.
timezone Time zone of the selection period in ±hh:mm format.
preset Preset of report.
dimensions Array of dimensions.
metrics Array of metrics.
sort Array of sortings.
date1 Start date of requesting data period in the format YYYY-MM-DD.
date2 End date of requesting data period in the format YYYY-MM-DD.
filters Segmentation filter.
limit Number of elements on results page.
offset Index of first row of requesting data, beginning with 1.
dimension Dimension value for specified tree level. For example, the second tree level was specified (length of transferred array parent_id equals one). In this case the field will contain the value of the second request dimension.
metrics Array of metric values for this row. Value of this array is a number or null.
expand Specify whether it is possible to reveal this row on the next level of the tree.