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.

Request

GET

https://api.appmetrica.yandex.net/stat/v1/data/bytime

Query parameters

Name

Description

params

Type: BytimeParams

Example: ``

statGroupParams

Type: StatGroupParams

Example: ``

BytimeParams

Name	Description
access_filter_id	Type: integer
accuracy	Type: string Example: `example`
annotation_groups	Type: string[] Example `[ "example" ]`
callback	Type: string Example: `example`
confidence_level	Type: string Default: `0.95`
date_dimension	Type: string Example: `example`
date1	Type: string Default: `6daysAgo`
date2	Type: string Default: `today`
dimensions	Type: string Example: `example`
direct_client_ids	Type: integer[] Example `[ 0 ]`
direct_client_logins	Type: string[] Example `[ "example" ]`
exclude_insignificant	Type: boolean
filters	Type: string Example: `example`
group	Type: string Группировка данных по времени: `all` — временной интервал не разбивается; `auto` — интервал устанавливается с учетом выбранного отчетного периода и количества данных, достаточного для этого периода; `minutes` — временной интервал разбивается на интервалы из некоторого количества минут. Возможные интервалы minutes: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. Расчеты оптимизированы так, чтобы между точками на графике не было больше одного интервала, с лимитом в 1600 точек для минут; `dekaminute` — временной интервал разбивается на 10-минутные интервалы; `minute` — временной интервал разбивается на минутные интервалы; `hour` — временной интервал разбивается на часовые интервалы; `hours` — временной интервал разбивается на интервалы из нескольких часов. Возможные интервалы hours: 1, 2, 3, 4, 6, 8, 12, 24. Расчеты оптимизированы так, чтобы между точками на графике не было больше одного интервала, с лимитом в 30 точек для часов; `day` — временной интервал разбивается по дням; `week` — временной интервал разбивается по неделям; `month` — временной интервал разбивается по месяцам; `quarter` — временной интервал разбивается по кварталам; `year` — временной интервал разбивается по годам. Default: `week`
ids	Type: integer[] Example `[ 0 ]`
include_annotations	Type: string Default: `false`
include_meta	Type: boolean
include_undefined	Type: boolean
keys_sort	Type: string Example: `example`
lang	Type: string Example: `example`
max_deviation	Type: string Default: `0.1`
metrics	Type: string Example: `example`
preset	Type: string Example: `example`
pretty	Type: string Default: `false`
proposed_accuracy	Type: boolean
reference_row_id	Type: string[] Example `[ "example" ]`
request_domain	Type: string Example: `example`
require_metric_values	Type: string Default: `false`
row_ids	Type: string[][] Example `[ [ "example" ] ]`
timezone	Type: string Example: `example`
top_keys	Type: string Default: `7`
with_confidence	Type: boolean

Example

{
  "ids": [
    0
  ],
  "direct_client_ids": [
    0
  ],
  "direct_client_logins": [
    "example"
  ],
  "date1": "6daysAgo",
  "date2": "today",
  "timezone": "example",
  "preset": "example",
  "metrics": "example",
  "dimensions": "example",
  "reference_row_id": [
    "example"
  ],
  "filters": "example",
  "accuracy": "example",
  "proposed_accuracy": true,
  "include_undefined": true,
  "include_meta": true,
  "with_confidence": true,
  "exclude_insignificant": true,
  "confidence_level": "0.95",
  "max_deviation": "0.1",
  "pretty": "false",
  "lang": "example",
  "request_domain": "example",
  "require_metric_values": "false",
  "access_filter_id": 0,
  "group": "week",
  "callback": "example",
  "date_dimension": "example",
  "row_ids": [
    [
      "example"
    ]
  ],
  "top_keys": "7",
  "keys_sort": "example",
  "include_annotations": "false",
  "annotation_groups": [
    "example"
  ]
}

StatGroupParams

Name

Description

label_id

Type: integer

Min value: 1

org_id

Type: integer

Min value: 1

Example

{
  "org_id": 1,
  "label_id": 1
}

Responses

200 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": "example",
        "allow_null": true,
        "sub_table": "example",
        "permission_scope": "example",
        "since": "example",
        "advanced": true,
        "required_keys": [
          "example"
        ],
        "features": [
          "example"
        ],
        "chained_attributes_group_name": "example",
        "chained_attributes_group_index": 0,
        "secret": true,
        "exposes_secret_data": true,
        "disjoint": true,
        "relations": [
          "example"
        ]
      }
    ],
    "metrics": [
      {
        "dim": "example",
        "metric_string": "example",
        "name": "example",
        "description": "example",
        "allow_normalisation": true,
        "require_dynamic_correction": true,
        "allow_filters": true,
        "type": "example",
        "allow_sort": true,
        "default_sort": "example",
        "advanced": true,
        "support_confidence": true,
        "negative": true,
        "parameters": [
          null
        ],
        "sub_table": "example",
        "required_dimension": "example",
        "permission_scope": "example",
        "since": "example",
        "required_keys": [
          "example"
        ],
        "features": [
          "example"
        ],
        "secret": true,
        "exposes_secret_data": true
      }
    ]
  },
  "total_rows": 0,
  "total_rows_rounded": true,
  "with_confidence": true,
  "exclude_insignificant": 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
    ]
  ],
  "last_period_index": 0,
  "time_intervals": [
    [
      "example"
    ]
  ],
  "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.
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": "example", "allow_null": true, "sub_table": "example", "permission_scope": "example", "since": "example", "advanced": true, "required_keys": [ "example" ], "features": [ "example" ], "chained_attributes_group_name": "example", "chained_attributes_group_index": 0, "secret": true, "exposes_secret_data": true, "disjoint": true, "relations": [ "example" ] } ], "metrics": [ { "dim": "example", "metric_string": "example", "name": "example", "description": "example", "allow_normalisation": true, "require_dynamic_correction": true, "allow_filters": true, "type": "example", "allow_sort": true, "default_sort": "example", "advanced": true, "support_confidence": true, "negative": true, "parameters": [ null ], "sub_table": "example", "required_dimension": "example", "permission_scope": "example", "since": "example", "required_keys": [ "example" ], "features": [ "example" ], "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 report period in the format YYYY-MM-DD. Example: `example`
date2	Type: string End date of the report period in the format YYYY-MM-DD. 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 The time zone of the selection period in the format ±hh:mm. 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
    ]
  ]
}

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

Sorting method:

asc
desc

Example: example

description

Type: string

Metric description

Example: example

dim

Type: string

Grouping data

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

Unique items: true

Example

[
  "example"
]

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": "example",
  "allow_null": true,
  "sub_table": "example",
  "permission_scope": "example",
  "since": "example",
  "advanced": true,
  "required_keys": [
    "example"
  ],
  "features": [
    "example"
  ],
  "chained_attributes_group_name": "example",
  "chained_attributes_group_index": 0,
  "secret": true,
  "exposes_secret_data": true,
  "disjoint": true,
  "relations": [
    "example"
  ]
}

Additional fields for the current dimension

Example

{}

group_name

Type: string

Names of dimensions when enumerating them

Example: example

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": "example",
  "allow_null": true,
  "sub_table": "example",
  "permission_scope": "example",
  "since": "example",
  "advanced": true,
  "required_keys": [
    "example"
  ],
  "features": [
    "example"
  ],
  "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 Sorting method: `asc` `desc` Example: `example`
description	Type: string Metric description Example: `example`
dim	Type: string Metric Example: `example`
exposes_secret_data	Type: boolean Discloses sensitive data
features	Type: string[] Tag characteristics required for metric use Unique items: `true` Example `[ "example" ]`
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. `int` `double` `second` `millisecond` `affinity` `percents` `currency` Example: `example`

Example

{
  "dim": "example",
  "metric_string": "example",
  "name": "example",
  "description": "example",
  "allow_normalisation": true,
  "require_dynamic_correction": true,
  "allow_filters": true,
  "type": "example",
  "allow_sort": true,
  "default_sort": "example",
  "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": [
    "example"
  ],
  "secret": true,
  "exposes_secret_data": true
}

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?

Drill down

All dimensions