--- metadata: - name: generator content: Diplodoc Platform v5.48.2 alternate: - https://yandex.com.tr/dev/metrika/en/stat/openapi/bytime.md - https://yandex.com.tr/dev/metrika/ru/stat/openapi/bytime.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/dev/metrika/en/llms.txt
# Get data by time 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.tr/dev/metrika/en/stat/examples.md#query) with this request. ## Request
GET {.openapi__method} ```text translate=no https://api-metrika.yandex.net/stat/v1/data/bytime ```
### 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.tr/dev/metrika/en/stat/sampling.md) (the number of sessions used for calculating results). _Example:_{.json-schema-reset .json-schema-example} `` {.table-cell} || || _annotation_groups_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string[] Groups of comma-separated comments to return in the response. Transmitted when the `include_annotations` parameter is set to `true` When the `annotation_groups` parameter is omitted, the response returns all the comments that were created for this tag. _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.tr/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.tr/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} || || _group_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Grouping data by time: - all: The time range is not broken down; - auto: The interval is set taking into account the selected report period and amount of data sufficient for this period; - minutes: The time range is divided into intervals of a certain number of minutes. Possible intervals: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. The calculations are optimized so that there is no more than one interval between points on the chart, with a limit of 1600 points for minutes; - `dekaminute`: The time interval is broken down into 10-minute intervals; - `minute`: The time interval is broken down into one-minute intervals; - `hour`: The time interval is broken down into hourly intervals; - `hours`: The time interval is broken down into intervals of several hours. Possible intervals: 1, 2, 3, 4, 6, 8, 12, 24. The calculations are optimized so that there is no more than one interval between points on the chart, with a limit of 30 points for hours; - `day`: The time interval is broken down into days; - `week`: The time interval is broken down into week; - `month`: The time range is divided into months; - `quarter`: The time range is divided into quarters; - `year`: The time interval is broken down into years. _Default:_{.json-schema-reset .json-schema-value} `week` _Example:_{.json-schema-reset .json-schema-example} `` {.table-cell} || || _include_annotations_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Used to include comments in the response. Disabled by default. _Default:_{.json-schema-reset .json-schema-value} `false` _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} || || _keys_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} || || _lang_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Language. _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.tr/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} || || _row_ids_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string[][] Row selection for building charts. Contains listing of key lists. _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} || || _top_keys_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Sets the number of rows of results if the `row_ids` parameter is not set. Maximum number of rows: 30. _Default:_{.json-schema-reset .json-schema-value} `7` _Example:_{.json-schema-reset .json-schema-example} `` {.table-cell} || |#{.json-schema-properties} ## Responses
## 200 OK OK
### Body {% cut "application/json" %} ```json translate=no { "query": { "timezone": "example", "preset": "example", "dimensions": [ "example" ], "metrics": [ "example" ], "sort": [ "example" ], "date1": "example", "date2": "example", "filters": "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 ] ], "annotations": [ [ { "id": 0, "date": "2025-01-01", "time": "12:00:00", "title": "example", "message": "example", "group": "example" } ] ] } ``` {% endcut %} #| || **Name** | **Description** || || _annotations_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: [ConstructorReportChartAnnotation](#entity-ConstructorReportChartAnnotation)[][] Comments. {% cut "**Example**" %}{.json-schema-example} ```json translate=no [ [ { "id": 0, "date": "2025-01-01", "time": "12:00:00", "title": "example", "message": "example", "group": "example" } ] ] ``` {% endcut %} {.table-cell} || || _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**: [DynamicRow](#entity-DynamicRow)[] {% 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**: [DynamicQueryExternal](#entity-DynamicQueryExternal) 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" } ``` {% 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[][] Total results for metrics across the entire dataset (after filtering). {% cut "**Example**" %}{.json-schema-example} ```json translate=no [ [ 0.5 ] ] ``` {% endcut %} {.table-cell} || |#{.json-schema-properties}
### DynamicQueryExternal {#entity-DynamicQueryExternal} 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} || || _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" } ``` {% endcut %}
### DynamicRow {#entity-DynamicRow} 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 %}
### ConstructorReportChartAnnotation {#entity-ConstructorReportChartAnnotation} #| || **Name** | **Description** || || _date_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string<date> Date. _Example:_{.json-schema-reset .json-schema-example} `2025-01-01` {.table-cell} || || _group_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Group: - `A`: Group A. - `B`: Group B. - `C`: Group C. - `D`: Group D. - `E`: Group E. - `HOLIDAY`: Public holidays. Shown when Yandex Metrica successfully detected the tag's region. _Example:_{.json-schema-reset .json-schema-example} `example` {.table-cell} || || _id_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: integer Comment ID. {.table-cell} || || _message_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Description. _Example:_{.json-schema-reset .json-schema-example} `example` {.table-cell} || || _time_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string<time> Time. _Example:_{.json-schema-reset .json-schema-example} `12:00:00` {.table-cell} || || _title_{.json-schema-reset .json-schema-property} {.table-cell}| **Type**: string Title. _Example:_{.json-schema-reset .json-schema-example} `example` {.table-cell} || |#{.json-schema-properties} {% cut "**Example**" %}{.json-schema-example} ```json translate=no { "id": 0, "date": "2025-01-01", "time": "12:00:00", "title": "example", "message": "example", "group": "example" } ``` {% endcut %}
[*Deprecated]: No longer supported, please use an alternative and newer version.