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.

Request

GET

https://api-metrica.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

Comma-separated list of metrics. 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. Passed if the parameter include_annotations takes the value true

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

A: Group A.

B: Group B.

C: Group C.

D: Group D.

E: Group E.

HOLIDAY: Public holidays. Shown when Yandex Metrica could detect the tag's region.

Enum: A, B, C, D, E, HOLIDAY

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

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 weeks.
  • 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

Enum: all, auto, minutes, dekaminute, minute, hour, hours, day, week, month, quarter, year

include_annotations

Type: string

Used to include comments in the response. Disabled by default.

Default: false

Example: ``

include_undefined

Type: boolean

Outputs 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 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.

row_ids

Type: string[][]

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

Example: -01:30, -01:00, -00:00, +00:00, +01:00, +01:30

top_keys

Type: string

Sets the number of rows of results if you don't set the parameter row_ids. Maximum number of rows: 30.

Default: 7

Example: ``

Responses

200 OK

OK

Body

application/json
{
  "query": {
    "ids": [
      0
    ],
    "timezone": "example",
    "preset": "example",
    "dimensions": [
      "example"
    ],
    "metrics": [
      "example"
    ],
    "sort": [
      "example"
    ],
    "date1": "example",
    "date2": "example",
    "filters": "example"
  },
  "data": [
    {
      "dimensions": [
        {}
      ],
      "metrics": [
        [
          0.5
        ]
      ]
    }
  ],
  "meta": {
    "dimensions": [
      {
        "id": "example",
        "dim": "example",
        "name": "example",
        "short_name": "example",
        "group_name": "example",
        "description": "example",
        "type": "example",
        "disallow_by_time": true,
        "allow_filters": true,
        "parameter": {
          "id": "example",
          "description": "example",
          "dim": "example"
        },
        "fields": {},
        "allow_sort": true,
        "default_sort": "asc",
        "allow_null": true,
        "sub_table": "example",
        "permission_scope": "example",
        "since": "example",
        "advanced": true,
        "required_keys": [
          "example"
        ],
        "features": [
          "offline_calls"
        ],
        "chained_attributes_group_name": "example",
        "chained_attributes_group_index": 0,
        "secret": true,
        "exposes_secret_data": true,
        "disjoint": true
      }
    ],
    "metrics": [
      {
        "dim": "example",
        "metric_string": "example",
        "name": "example",
        "description": "example",
        "allow_normalisation": true,
        "require_dynamic_correction": true,
        "allow_filters": true,
        "type": "int",
        "allow_sort": true,
        "default_sort": "asc",
        "advanced": true,
        "support_confidence": true,
        "negative": true,
        "parameters": [
          null
        ],
        "sub_table": "example",
        "required_dimension": "example",
        "permission_scope": "example",
        "since": "example",
        "required_keys": [
          "example"
        ],
        "features": [
          "offline_calls"
        ],
        "secret": true,
        "exposes_secret_data": true
      }
    ]
  },
  "total_rows": 0,
  "total_rows_rounded": true,
  "sampled": true,
  "sampleable": true,
  "contains_sensitive_data": true,
  "sample_share": 0.5,
  "max_sample_share": 0.5,
  "min_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": "A"
      }
    ]
  ]
}

Name

Description

annotations

Type: MetrikaReportChartAnnotation[][]

Comments.

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

contains_sensitive_data

Type: boolean

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.

data

Type: DynamicRow[]

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

data_lag

Type: integer

Delay in updating data, in seconds.

meta

Type: Meta

Request metadata. Contains a description of request dimensions and metrics.

Example
{
  "dimensions": [
    {
      "id": "example",
      "dim": "example",
      "name": "example",
      "short_name": "example",
      "group_name": "example",
      "description": "example",
      "type": "example",
      "disallow_by_time": true,
      "allow_filters": true,
      "parameter": {
        "id": "example",
        "description": "example",
        "dim": "example"
      },
      "fields": {},
      "allow_sort": true,
      "default_sort": "asc",
      "allow_null": true,
      "sub_table": "example",
      "permission_scope": "example",
      "since": "example",
      "advanced": true,
      "required_keys": [
        "example"
      ],
      "features": [
        "offline_calls"
      ],
      "chained_attributes_group_name": "example",
      "chained_attributes_group_index": 0,
      "secret": true,
      "exposes_secret_data": true,
      "disjoint": true
    }
  ],
  "metrics": [
    {
      "dim": "example",
      "metric_string": "example",
      "name": "example",
      "description": "example",
      "allow_normalisation": true,
      "require_dynamic_correction": true,
      "allow_filters": true,
      "type": "int",
      "allow_sort": true,
      "default_sort": "asc",
      "advanced": true,
      "support_confidence": true,
      "negative": true,
      "parameters": [
        null
      ],
      "sub_table": "example",
      "required_dimension": "example",
      "permission_scope": "example",
      "since": "example",
      "required_keys": [
        "example"
      ],
      "features": [
        "offline_calls"
      ],
      "secret": true,
      "exposes_secret_data": true
    }
  ]
}

query

Type: DynamicQueryExternal

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

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

sample_share

Type: number

Percentage of data used for the calculation. Available values range from 0 to 1.

sample_size

Type: integer

Number of rows in the requested data.

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 (with filtration).

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, and the inner arrays list values of a specific metric for each time group.

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

ParamMetaExternal

List of metric parameters

Name

Description

description

Type: string

Parameter description

Example: example

dim

Type: string

Name of a dimension with values

Example: example

id

Type: string

Parameter ID

Example: example
Example
{
  "id": "example",
  "description": "example",
  "dim": "example"
}

DimensionMetaExternal

Name

Description

advanced

Type: boolean

Dimension for an advanced user

allow_filters

Type: boolean

Whether filters can be used

allow_null

Type: boolean

Whether "Undefined" can be shown for this dimension

allow_sort

Type: boolean

Whether sorting by this dimension is allowed

chained_attributes_group_index

Type: integer

Dimension order in a group of linked dimensions

chained_attributes_group_name

Type: string

Name of a group of linked dimensions

Example: example

default_sort

Type: string

Default sorting method

Enum: asc, desc

description

Type: string

Metric description

Example: example

dim

Type: string

Dimension

Example: example

disallow_by_time

Type: boolean

Whether this dimension is allowed along with grouping data by time.

features

Type: string[]

Tag characteristics required for dimension use

Example
[
  "offline_calls"
]

fields
Type: object

[additional]

Type: DimensionMetaExternal

Example
{
  "id": "example",
  "dim": "example",
  "name": "example",
  "short_name": "example",
  "group_name": "example",
  "description": "example",
  "type": "example",
  "disallow_by_time": true,
  "allow_filters": true,
  "parameter": {
    "id": "example",
    "description": "example",
    "dim": "example"
  },
  "fields": {},
  "allow_sort": true,
  "default_sort": "asc",
  "allow_null": true,
  "sub_table": "example",
  "permission_scope": "example",
  "since": "example",
  "advanced": true,
  "required_keys": [
    "example"
  ],
  "features": [
    "offline_calls"
  ],
  "chained_attributes_group_name": "example",
  "chained_attributes_group_index": 0,
  "secret": true,
  "exposes_secret_data": true,
  "disjoint": true
}

Additional fields for the current dimension

Example
{}

group_name

Type: string

Names of dimensions when enumerating them

Example: example

id

Type: string

Dimension ID without any prefix or parameters

Example: example

name

Type: string

Dimension name

Example: example

parameter

Type: ParamMetaExternal

List of metric parameters

Example
{
  "id": "example",
  "description": "example",
  "dim": "example"
}

permission_scope

Type: string

Dimension access group

Example: example

required_keys

Type: string[]

Example
[
  "example"
]

short_name

Type: string

Dimension name

Example: example

since

Type: string

Date when dimension data appeared

Example: example

sub_table

Type: string

Subtable

Example: example

type

Type: string

Dimension interface type

Example: example
Example
{
  "id": "example",
  "dim": "example",
  "name": "example",
  "short_name": "example",
  "group_name": "example",
  "description": "example",
  "type": "example",
  "disallow_by_time": true,
  "allow_filters": true,
  "parameter": {
    "id": "example",
    "description": "example",
    "dim": "example"
  },
  "fields": {},
  "allow_sort": true,
  "default_sort": "asc",
  "allow_null": true,
  "sub_table": "example",
  "permission_scope": "example",
  "since": "example",
  "advanced": true,
  "required_keys": [
    "example"
  ],
  "features": [
    "offline_calls"
  ],
  "chained_attributes_group_name": "example",
  "chained_attributes_group_index": 0
}

MetricMetaExternal

Array of request metric metadata.

Name

Description

advanced

Type: boolean

Metric for advanced users

allow_filters

Type: boolean

Whether filters can be used

allow_normalisation

Type: boolean

Whether values can be normalized

allow_sort

Type: boolean

Whether data can be sorted by this metric

default_sort

Type: string

Default sorting method

Enum: asc, desc

description

Type: string

Metric description

Example: example

dim

Type: string

Yandex Metrica

Example: example

exposes_secret_data

Type: boolean

Discloses sensitive data

features

Type: string[]

Tag characteristics required for metric use

Example
[
  "offline_calls"
]

metric_string

Type: string

Metric with a parameter value

Example: example

name

Type: string

Metric name

Example: example

negative

Type: boolean

Whether the metric is a negative indicator in terms of data interpretation, for example, the bounce rate, robot percentage, and so on.

parameters

Type: ParamMetaExternal[]

List of metric parameters

Example
[
  {
    "id": "example",
    "description": "example",
    "dim": "example"
  }
]

permission_scope

Type: string

Metric access group

Example: example

require_dynamic_correction

Type: boolean

Whether values require adjustments in the time report

required_dimension

Type: string

Dimension required for the metric

Example: example

required_keys

Type: string[]

Example
[
  "example"
]

secret

Type: boolean

Contains sensitive data

since

Type: string

Date when metric data appeared

Example: example

sub_table

Type: string

Subtable

Example: example

support_confidence

Type: boolean

Whether confidence can be estimated by this metric

type

Type: string

Metric type

Enum: int, double, second, millisecond, affinity, percents, currency
Example
{
  "dim": "example",
  "metric_string": "example",
  "name": "example",
  "description": "example",
  "allow_normalisation": true,
  "require_dynamic_correction": true,
  "allow_filters": true,
  "type": "int",
  "allow_sort": true,
  "default_sort": "asc",
  "advanced": true,
  "support_confidence": true,
  "negative": true,
  "parameters": [
    {
      "id": "example",
      "description": "example",
      "dim": "example"
    }
  ],
  "sub_table": "example",
  "required_dimension": "example",
  "permission_scope": "example",
  "since": "example",
  "required_keys": [
    "example"
  ],
  "features": [
    "offline_calls"
  ],
  "secret": true,
  "exposes_secret_data": true
}

Meta

Request metadata. Contains a description of request dimensions and metrics.

Name

Description

dimensions

Type: DimensionMetaExternal[]

Example
[
  {
    "id": "example",
    "dim": "example",
    "name": "example",
    "short_name": "example",
    "group_name": "example",
    "description": "example",
    "type": "example",
    "disallow_by_time": true,
    "allow_filters": true,
    "parameter": {
      "id": "example",
      "description": "example",
      "dim": "example"
    },
    "fields": {},
    "allow_sort": true,
    "default_sort": "asc",
    "allow_null": true,
    "sub_table": "example",
    "permission_scope": "example",
    "since": "example",
    "advanced": true,
    "required_keys": [
      "example"
    ],
    "features": [
      "offline_calls"
    ],
    "chained_attributes_group_name": "example",
    "chained_attributes_group_index": 0,
    "secret": true,
    "exposes_secret_data": true,
    "disjoint": true
  }
]

metrics

Type: MetricMetaExternal[]

Example
[
  {
    "dim": "example",
    "metric_string": "example",
    "name": "example",
    "description": "example",
    "allow_normalisation": true,
    "require_dynamic_correction": true,
    "allow_filters": true,
    "type": "int",
    "allow_sort": true,
    "default_sort": "asc",
    "advanced": true,
    "support_confidence": true,
    "negative": true,
    "parameters": [
      {
        "id": "example",
        "description": "example",
        "dim": "example"
      }
    ],
    "sub_table": "example",
    "required_dimension": "example",
    "permission_scope": "example",
    "since": "example",
    "required_keys": [
      "example"
    ],
    "features": [
      "offline_calls"
    ],
    "secret": true,
    "exposes_secret_data": true
  }
]
Example
{
  "dimensions": [
    {
      "id": "example",
      "dim": "example",
      "name": "example",
      "short_name": "example",
      "group_name": "example",
      "description": "example",
      "type": "example",
      "disallow_by_time": true,
      "allow_filters": true,
      "parameter": {
        "id": "example",
        "description": "example",
        "dim": "example"
      },
      "fields": {},
      "allow_sort": true,
      "default_sort": "asc",
      "allow_null": true,
      "sub_table": "example",
      "permission_scope": "example",
      "since": "example",
      "advanced": true,
      "required_keys": [
        "example"
      ],
      "features": [
        "offline_calls"
      ],
      "chained_attributes_group_name": "example",
      "chained_attributes_group_index": 0,
      "secret": true,
      "exposes_secret_data": true,
      "disjoint": true
    }
  ],
  "metrics": [
    {
      "dim": "example",
      "metric_string": "example",
      "name": "example",
      "description": "example",
      "allow_normalisation": true,
      "require_dynamic_correction": true,
      "allow_filters": true,
      "type": "int",
      "allow_sort": true,
      "default_sort": "asc",
      "advanced": true,
      "support_confidence": true,
      "negative": true,
      "parameters": [
        null
      ],
      "sub_table": "example",
      "required_dimension": "example",
      "permission_scope": "example",
      "since": "example",
      "required_keys": [
        "example"
      ],
      "features": [
        "offline_calls"
      ],
      "secret": true,
      "exposes_secret_data": true
    }
  ]
}

MetrikaReportChartAnnotation

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 could detect the tag's region.

Enum: A, B, C, D, E, HOLIDAY

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": "A"
}

No longer supported, please use an alternative and newer version.

Previous
Comparison — drill down
Next
Introduction