Getting data by time

Used to get data broken down by time period (for example, by day, week, or month). Use this request type to create charts and track statistics over time.

See an example with this request.

  1. Request syntax
  2. Response format

Request syntax

https://api-metrika.yandex.net/stat/v1/data/bytime
 ? ids=<int,int,...>
 & metrics=<string>
 & [accuracy=<string>]
 & [annotation_groups=<list>]
 & [callback=<string>]
 & [date1=<string>]
 & [date2=<string>]
 & [dimensions=<string>]
 & [direct_client_logins=<string,_string,...>]
 & [filters=<string>]
 & [group=<group_type>]
 & [id=<integer>]
 & [include_annotations=<boolean>]
 & [include_undefined=<boolean>]
 & [lang=<string>]
 & [preset=<string>]
 & [pretty=<boolean>]
 & [proposed_accuracy=<boolean>]
 & [row_ids=<list>]
 & [timezone=<string>]
 & [top_keys=<integer>]
ids *Comma-separated list of counter IDs. Used instead of the id parameter.
metrics *

Comma-separated list of metrics.

Limit: 20 metrics per request.

accuracySample size for the report. Use it to control the sampling rate (the number of sessions used for calculating results).

Default value: medium

annotation_groups

Groups of comma-separated comments to return in the response. Transmitted if the include_annotations parameter is set to true.

If the annotation_groups parameter is omitted, the response returns all the comments that were created for this tag.

Acceptable values:

  • A: Group A.
  • B: Group B.
  • C: Group C.
  • D: Group D.
  • E: Group E.
  • MONITORING: Results of checking site availability.
  • HOLIDAY: Public holidays. Shown when Yandex Metrica could detect the tag's region.
callbackCallback function that processes the API response.
date1

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

Default value: 6daysAgo

date2

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

Default value: today

dimensions

Comma-separated list of dimensions.

Limit: 10 dimensions per request.

direct_client_loginsComma-separated usernames of Yandex Direct clients. They can be used for generating the Yandex Direct — costs report.
filters

Segmentation 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 condition.

groupGrouping data by time.

Default value: week

Acceptable values:

  • 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 weeks.
  • month: The time interval is broken down into months.
  • quarter: The time interval is broken down into quarters.
  • year: The time interval is broken down into years.
idTag ID. Obsolete. Use ids.
include_annotationsUsed to include comments in the response. Disabled by default.

Default value: false

include_undefinedOutputs rows that don't have defined dimension values. This only affects the first dimension. Disabled by default.
langLanguage.
presetReport presets.
prettySpecifies the formatting for results. To use formatting, set the value to true.

Default value: false

proposed_accuracyIf the parameter is set to true, the API has the right to automatically increase the "accuracy" parameter to the recommended value. This can help you obtain meaningful results when a request is sent to a small table with very small sampling.
row_idsRow selection for creating charts. Contains listing of key lists.
timezone

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 when calculating the request sample period as well as the date- and time-specific dimensions. By default, the tag's time zone is used.

top_keys

Sets the number of rows of results if the row_ids parameter is not set.

Default value: 7

ids *Comma-separated list of counter IDs. Used instead of the id parameter.
metrics *

Comma-separated list of metrics.

Limit: 20 metrics per request.

accuracySample size for the report. Use it to control the sampling rate (the number of sessions used for calculating results).

Default value: medium

annotation_groups

Groups of comma-separated comments to return in the response. Transmitted if the include_annotations parameter is set to true.

If the annotation_groups parameter is omitted, the response returns all the comments that were created for this tag.

Acceptable values:

  • A: Group A.
  • B: Group B.
  • C: Group C.
  • D: Group D.
  • E: Group E.
  • MONITORING: Results of checking site availability.
  • HOLIDAY: Public holidays. Shown when Yandex Metrica could detect the tag's region.
callbackCallback function that processes the API response.
date1

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

Default value: 6daysAgo

date2

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

Default value: today

dimensions

Comma-separated list of dimensions.

Limit: 10 dimensions per request.

direct_client_loginsComma-separated usernames of Yandex Direct clients. They can be used for generating the Yandex Direct — costs report.
filters

Segmentation 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 condition.

groupGrouping data by time.

Default value: week

Acceptable values:

  • 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 weeks.
  • month: The time interval is broken down into months.
  • quarter: The time interval is broken down into quarters.
  • year: The time interval is broken down into years.
idTag ID. Obsolete. Use ids.
include_annotationsUsed to include comments in the response. Disabled by default.

Default value: false

include_undefinedOutputs rows that don't have defined dimension values. This only affects the first dimension. Disabled by default.
langLanguage.
presetReport presets.
prettySpecifies the formatting for results. To use formatting, set the value to true.

Default value: false

proposed_accuracyIf the parameter is set to true, the API has the right to automatically increase the "accuracy" parameter to the recommended value. This can help you obtain meaningful results when a request is sent to a small table with very small sampling.
row_idsRow selection for creating charts. Contains listing of key lists.
timezone

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 when calculating the request sample period as well as the date- and time-specific dimensions. By default, the tag's time zone is used.

top_keys

Sets the number of rows of results if the row_ids parameter is not set.

Default value: 7

* Required

Response format


{
    "total_rows" :  < long > ,
    "total_rows_rounded" :  < boolean > ,
    "sampled" :  < boolean > ,
    "contains_sensitive_data" :  < boolean > ,
    "sample_share" :  < double > ,
    "sample_size" :  < long > ,
    "sample_space" :  < long > ,
    "data_lag" :  < int > ,
    "query" : {
        "timezone" :  < string > ,
        "preset" :  < string > ,
        "dimensions" : [  < string > , ... ],
        "metrics" : [  < string > , ... ],
        "sort" : [  < string > , ... ],
        "date1" :  < string > ,
        "date2" :  < string > ,
        "filters" :  < string > 
    },
    "data" : [ {
        "dimensions" : [ {
            "key_1" :  < string > ,
            "key_2" : ...
        }, ... ],
        "metrics" : [ [  < double > , ... ], ... ]
    }, ... ],
    "totals" : [ [  < double > , ... ], ... ],
    "annotations" : [ [ {
        "id" :  < int > ,
        "date" :  < local_date > ,
        "time" :  < local_time > ,
        "title" :  < string > ,
        "message" :  < string > ,
        "group" :  < chart_annotation_group > 
    }, ... ], ... ]
}
Parameters Description
total_rows The total number of rows in the response for the entire dataset (after filtering).
total_rows_rounded Indicates that the total number of rows was rounded.
sampled Sampling flag. Indicates whether sampling was applied. Possible values: true, false.
contains_sensitive_data

Indicates whether sensitive data can be omitted from the response. This 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.

sample_share Percentage of data used for the calculation. Available values range from 0 to 1.
sample_size Number of rows in the requested data.
sample_space Number of data rows.
data_lag Delay in updating data, in seconds.
query Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization.
data Response rows. An array in which each item is a single row of the result.
totals Total results for metrics across the entire dataset (with filtration).
annotations Comments.
query
timezone Time zone of the sample period in ±hh:mm format.
preset Report preset.
dimensions Array of dimensions.
metrics Array of metrics.
sort Array of sortings.
date1 Start date of the sample period in YYYY-MM-DD format.
date2 End date of the sample period in YYYY-MM-DD format.
filters Segmentation filter.
data
dimensions 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.
metrics Array of arrays of metric values for this row. The outer array lists metrics, and the inner arrays list values of a specific metric for each time group.
annotations
id Comment ID.
date Date.
time Time.
title Title.
message Description.
group The group.

Possible values:

  • A: Group A.
  • B: Group B.
  • C: Group C.
  • D: Group D.
  • E: Group E.
  • MONITORING: Results of checking site availability.
  • HOLIDAY: Public holidays. Shown when Yandex Metrica could detect the tag's region.
Parameters Description
total_rows The total number of rows in the response for the entire dataset (after filtering).
total_rows_rounded Indicates that the total number of rows was rounded.
sampled Sampling flag. Indicates whether sampling was applied. Possible values: true, false.
contains_sensitive_data

Indicates whether sensitive data can be omitted from the response. This 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.

sample_share Percentage of data used for the calculation. Available values range from 0 to 1.
sample_size Number of rows in the requested data.
sample_space Number of data rows.
data_lag Delay in updating data, in seconds.
query Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization.
data Response rows. An array in which each item is a single row of the result.
totals Total results for metrics across the entire dataset (with filtration).
annotations Comments.
query
timezone Time zone of the sample period in ±hh:mm format.
preset Report preset.
dimensions Array of dimensions.
metrics Array of metrics.
sort Array of sortings.
date1 Start date of the sample period in YYYY-MM-DD format.
date2 End date of the sample period in YYYY-MM-DD format.
filters Segmentation filter.
data
dimensions 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.
metrics Array of arrays of metric values for this row. The outer array lists metrics, and the inner arrays list values of a specific metric for each time group.
annotations
id Comment ID.
date Date.
time Time.
title Title.
message Description.
group The group.

Possible values:

  • A: Group A.
  • B: Group B.
  • C: Group C.
  • D: Group D.
  • E: Group E.
  • MONITORING: Results of checking site availability.
  • HOLIDAY: Public holidays. Shown when Yandex Metrica could detect the tag's region.