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 with this request.

Request

GET

https://api-metrika.yandex.net/stat/v1/data/bytime

Query parameters

Name	Description
ids	Type: integer[] Comma-separated list of tag IDs. Example: `44147844,2215573`
metrics	Type: string List of metrics separated by comma. Limit: 20 metrics per request. Example: `ym:s:pageviews`
accuracy	Type: string Sample size for the report. Use it to control the sampling rate (the number of sessions used for calculating results). Example: ``
annotation_groups	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: ``
callback	Type: string Callback function that processes the API response. Example: ``
date1	Type: string Start date of the sample period in YYYY-MM-DD format. You can also use the values: `today`, `yesterday`, `ndaysAgo`. Default: `6daysAgo` Example: ``
date2	Type: string End date of the sample period in YYYY-MM-DD format. You can also use the values: `today`, `yesterday`, `ndaysAgo`. Default: `today` Example: ``
dimensions	Type: string Comma-separated list of dimensions. Limit: 10 dimensions per request. Example: `ym:s:trafficSource`
direct_client_logins	Type: string[] Comma-separated usernames of Yandex Direct clients. Can be used for generating the Yandex Direct — costs report. Example: `login1,login2`
filters	Type: string 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 criteria. Example: ``
group	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: `week` Example: ``
include_annotations	Type: string Used to include comments in the response. Disabled by default. Default: `false` Example: ``
include_undefined	Type: boolean The response will include rows that don't have defined dimension values. This only affects the first dimension. Disabled by default.
keys_sort	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: ``
lang	Type: string Language. Example: ``
preset	Type: string Report presets. Example: `sources_summary`
pretty	Type: string Specifies the formatting for results. To use formatting, set the value to `true`. Default: `false` Example: ``
proposed_accuracy	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.
row_ids	Type: string[][] Row selection for building charts. Contains listing of key lists. Example: ``
timezone	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: `+03:00`
top_keys	Type: string Sets the number of rows of results if the `row_ids` parameter is not set. Maximum number of rows: 30. Default: `7` Example: ``

Responses

200 OK

Body

application/json

{
  "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"
      }
    ]
  ]
}

Name	Description
annotations	Type: ConstructorReportChartAnnotation[][] Comments. Example `[ [ { "id": 0, "date": "2025-01-01", "time": "12:00:00", "title": "example", "message": "example", "group": "example" } ] ]`
contains_sensitive_data	Type: boolean Indicates whether sensitive data 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`.
data	Type: DynamicRow[] Example `[ { "dimensions": [ {} ], "metrics": [ [ 0.5 ] ] } ]`
data_lag	Type: integer Delay in updating data, in seconds.
query	Type: DynamicQueryExternal Original request. Contains the request parameters, including detailed parameters from the template and parameters for attribute parametrization. Example `{ "timezone": "example", "preset": "example", "dimensions": [ "example" ], "metrics": [ "example" ], "sort": [ "example" ], "date1": "example", "date2": "example", "filters": "example" }`
sample_share	Type: number Share of data used for the calculation. Available value ranges from 0 to 1.
sample_size	Type: integer Number of rows in the data sample.
sample_space	Type: integer Number of data rows.
sampled	Type: boolean Sampling flag. Indicates whether sampling was applied. Possible values: `true`, `false`.
total_rows	Type: integer The total number of rows in the response for the entire dataset (after filtering).
total_rows_rounded	Type: boolean Indicates that the total number of rows was rounded.
totals	Type: number[][] Total results for metrics across the entire dataset (after filtering). Example `[ [ 0.5 ] ]`

DynamicQueryExternal

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

Name	Description
date1	Type: string Start date of the sample period in YYYY-MM-DD format. Example: `example`
date2	Type: string End date of the sample period in YYYY-MM-DD format. Example: `example`
dimensions	Type: string[] Example `[ "example" ]`
filters	Type: string Segmentation filter. Example: `example`
metrics	Type: string[] Example `[ "example" ]`
preset	Type: string Report preset. Example: `example`
sort	Type: string[] Example `[ "example" ]`
timezone	Type: string Time zone of the sample period in ±hh:mm format. Example: `example`

Example

{
  "timezone": "example",
  "preset": "example",
  "dimensions": [
    "example"
  ],
  "metrics": [
    "example"
  ],
  "sort": [
    "example"
  ],
  "date1": "example",
  "date2": "example",
  "filters": "example"
}

DynamicRow

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

Name

Description

dimensions

Type: object[]

[additional]

Type: string

Example: example

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.

Example

[
  {}
]

metrics

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.

Example

[
  [
    0.5
  ]
]

Example

{
  "dimensions": [
    {}
  ],
  "metrics": [
    [
      0.5
    ]
  ]
}

ConstructorReportChartAnnotation

Name	Description
date	Type: string<date> Date. Example: `2025-01-01`
group	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: `example`
id	Type: integer Comment ID.
message	Type: string Description. Example: `example`
time	Type: string<time> Time. Example: `12:00:00`
title	Type: string Title. Example: `example`

Example

{
  "id": 0,
  "date": "2025-01-01",
  "time": "12:00:00",
  "title": "example",
  "message": "example",
  "group": "example"
}

Was the article helpful?

Comparison — drill down

Introduction