API Яндекс Метрики: что это, как получить токен и выгрузить данные

Интерфейса Метрики хватает, пока отчётов немного и смотреть их можно руками. Когда нужно каждый день собирать данные десятка счётчиков в одну таблицу, объединять визиты с продажами из CRM или строить отчёты в BI, на помощь приходит программный интерфейс.

Разберём, какие интерфейсы есть у Метрики, как получить токен, как сделать первый запрос к отчётам и выгрузить сырые данные через Logs API.

Примеры кода — рабочие, но токен и номер счётчика в них нужно заменить на свои.

Зачем нужен программный доступ

Программный интерфейс позволяет другим системам обращаться к Метрике без браузера. Скрипт отправляет запрос с токеном и получает ответ в формате JSON или CSV.

Всё, что вы делаете в интерфейсе руками, можно автоматизировать: строить отчёты, создавать цели, загружать расходы.

Кому это нужно:

• агентствам — собирать отчёты по десяткам клиентов в одну систему;
• аналитикам — объединять данные Метрики с CRM, рекламой и продажами в BI;
• разработчикам — встраивать статистику в свои сервисы и админки;
• маркетологам — автоматически выгружать отчёты в таблицы.

Четыре вида интерфейсов

API управления

Работа с объектами Метрики: создать тег и изменить его настройки, добавить цель или фильтр, выдать права доступа. Здесь же управление данными о клиентах и заказах из CRM.

API импорта данных

Загрузка в Метрику внешних данных: расходов на рекламу, клиентов и заказов из CRM, звонков, офлайн-конверсий и параметров посетителей.

На этом строится сквозная аналитика.

API отчётов

Те же отчёты, что в интерфейсе, но в машиночитаемом виде: с сегментацией, полным набором группировок и метрик, сравнением сегментов. Это самый востребованный вид API.

Logs API

Неагрегированные данные — каждый визит и каждый просмотр отдельной строкой. Подходит тем, кто сам обрабатывает статистику и хранит её, например, в ClickHouse.

Как получить токен

Все методы требуют авторизации через OAuth-токен Яндекса. Порядок такой:

1. Откройте Яндекс OAuth и создайте приложение, выбрав пункт «Для доступа к API или отладки».
2. Укажите название приложения и почту для связи.
3. В поле «Доступ к данным» введите metrika и выберите нужные права.
4. Нажмите «Создать приложение» и скопируйте его ClientID.
5. Откройте ссылку вида oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID> и скопируйте токен со страницы.

Какие доступы выбрать

Выдавайте приложению минимум прав. Для выгрузки отчётов достаточно metrika:read.

Доступы на загрузку расходов, параметров и офлайн-данных не нужны, если уже выбран metrika:write.

Токен даёт доступ к тем же счётчикам, что и аккаунт, от имени которого он получен.

Если нужны данные клиента, попросите у него гостевой доступ для вашего логина — подробнее в статье о доступе к Метрике.

Как хранить токен

• не вставляйте его прямо в код, который попадает в репозиторий;
• не пересылайте в мессенджерах и не храните в общих таблицах;
• используйте переменные окружения или менеджер секретов;
• если токен утёк, отзовите доступ приложения и получите новый.

Первый запрос к отчётам

Запросы отправляются на api-metrika.yandex.net. Токен передаётся в заголовке Authorization. Отчёт строится из двух частей:

• группировки (dimensions) — по чему группировать: источник, страница, устройство;
• метрики (metrics) — что считать: визиты, отказы, глубину, цели.

У группировок и метрик есть префиксы: ym:s: для визитов и ym:pv: для просмотров. В одном запросе их смешивать нельзя.

Пример: визиты по источникам

curl -H "Authorization: OAuth ВАШ_ТОКЕН" \
  "https://api-metrika.yandex.net/stat/v1/data?ids=XXXXXXXX&metrics=ym:s:visits,ym:s:bounceRate&dimensions=ym:s:lastTrafficSource&date1=30daysAgo&date2=yesterday"
 
Где XXXXXXXX — номер счётчика.
 
Ответ придёт в JSON: список источников с числом визитов и долей отказов за последние 30 дней.
 
Тот же запрос на Python
 
import os
import requests

token = os.environ["METRIKA_TOKEN"]
params = {
    "ids": "XXXXXXXX",
    "metrics": "ym:s:visits,ym:s:bounceRate",
    "dimensions": "ym:s:lastTrafficSource",
    "date1": "30daysAgo",
    "date2": "yesterday",
}
r = requests.get(
    "https://api-metrika.yandex.net/stat/v1/data",
    params=params,
    headers={"Authorization": f"OAuth {token}"},
)
for row in r.json()["data"]:
    print(row["dimensions"][0]["name"], row["metrics"])
 
Если заменить data на data.csv, ответ придёт в формате CSV — его удобно сразу открыть в таблице.
 
Logs API: выгрузка сырых данных
 
Logs API отдаёт не готовые отчёты, а отдельные визиты или просмотры со всеми нужными полями.
 
Работа с ним идёт в несколько шагов, потому что выгрузка готовится на стороне Метрики.
 
 
 
Оценить запрос методом evaluate — хватит ли квоты на выбранный период и поля.
 
Создать запрос логов с датами, списком полей и источником: visits или hits.
 
Дождаться, пока статус станет processed.
 
Скачать готовый файл — он может быть разбит на несколько частей.
 
Очистить запрос, чтобы освободить квоту хранилища.
 
 
GET  /management/v1/counter/XXXXXXXX/logrequests/evaluate?date1=2026-09-01&date2=2026-09-30&fields=ym:s:visitID,ym:s:dateTime,ym:s:lastTrafficSource&source=visits
POST /management/v1/counter/XXXXXXXX/logrequests?…те же параметры…
GET  /management/v1/counter/XXXXXXXX/logrequest/ID_ЗАПРОСА
GET  /management/v1/counter/XXXXXXXX/logrequest/ID_ЗАПРОСА/part/0/download
POST /management/v1/counter/XXXXXXXX/logrequest/ID_ЗАПРОСА/clean
 
Ограничения Logs API
 
 
данные за текущий день недоступны — запрашивайте вчерашний день и раньше;
 
период одного запроса — не больше года;
 
список полей — не длиннее 3000 символов;
 
общий объём подготовленных логов на счётчик — 10 ГБ; регулярно удаляйте скачанные файлы;
 
визиты дополняются по мере поступления данных: в среднем 99 % завершаются в течение трёх дней.
 
 
Цифры в Logs API и в интерфейсе могут немного отличаться: интерфейс применяет дополнительные алгоритмы обработки. Это нормально.
 
Квоты и ошибки
 
У сервиса есть ограничения на интенсивность запросов. При превышении сервер отвечает статусом 429 Too Many Requests и указывает, какая квота закончилась.
 
 
 
 
Ограничение
 
Квота
 
 
 
 
 
Запросов с одного IP к API
 
30 в секунду
 
 
 
Запросов с одного IP к Logs API
 
10 в секунду
 
 
 
Параллельных запросов на пользователя
 
3
 
 
 
Запросов на пользователя в сутки
 
5000
 
 
 
Запросов к API отчётов
 
200 за 5 минут
 
 
 
 
Частые ошибки:
 
 
401 Unauthorized — токен не передан или недействителен;
 
403 — у приложения нет нужного доступа или у аккаунта нет прав на тег;
 
429 — превышена квота: делайте паузы между запросами и не запускайте больше трёх одновременно;
 
400 — несовместимые группировки и метрики или ошибка в параметрах.
 
 
Загрузка данных в Метрику
 
Обратное направление — отправить данные в Метрику. Через интерфейс импорта загружают расходы на рекламу не из Директа, клиентов и заказы из CRM, звонки и офлайн-конверсии. После загрузки они появляются в отчётах и могут использоваться в рекламе.
 
Если CRM популярная, программировать не обязательно: многие системы подключаются через раздел «Интеграции».
 
Например, связка с Битрикс24 разобрана в статье про Метрику и Битрикс.
 
Типичные сценарии автоматизации
 
Чтобы понять, стоит ли браться за скрипты, посмотрите на готовые сценарии.
 
Ежедневный отчёт агентства. Скрипт каждое утро собирает визиты, отказы и цели по всем клиентам и складывает в общую таблицу. Менеджер видит просадки до планёрки.
 
Окупаемость рекламы. Расходы из рекламных кабинетов и заказы из CRM загружаются в Метрику, а отчёт по окупаемости строится автоматически.
 
Хранилище данных. Сырые визиты через Logs API каждый день уходят в базу, где их объединяют с данными сайта, CRM и колл-центра.
 
Мониторинг. Скрипт раз в час проверяет, что визиты продолжают поступать, и присылает уведомление, если счётчик вдруг замолчал после обновления сайта.
 
Массовая настройка. Агентство создаёт одинаковые цели и фильтры сразу на десятках проектов, не открывая каждый вручную.
 
Когда можно без программирования
 
Программирование нужно не всегда. Прежде чем писать скрипты, проверьте более простые варианты:
 
 
любой отчёт выгружается из интерфейса в Excel, CSV или PDF кнопкой экспорта;
 
отчёты можно отправлять по расписанию на почту;
 
для регулярной выгрузки в таблицы и BI есть готовые коннекторы и сервисы;
 
для связки с CRM и коллтрекингом — готовые интеграции в разделе «Интеграции».
 
 
Скрипты оправданы, когда данных много, источников несколько и нужна своя логика обработки.
 
Обзор основных отчётов, которые стоит выгружать, — в статье об отчётах Метрики.
 
Частые вопросы при старте
 
Нужен ли отдельный аккаунт для интеграций
 
Не обязательно, но удобно. Технический аккаунт с гостевым доступом к нужным счётчикам защищает от ситуации, когда сотрудник уволился, а все интеграции были привязаны к его логину.
 
Почему выгруженные цифры не совпадают с интерфейсом
 
Проверьте модель атрибуции, сегмент, фильтр роботов и семплирование. В интерфейсе они выставлены по умолчанию, а в запросах их нужно задавать явно параметрами.
 
Как устроены основные показатели, разобрано в статье про визиты и посетителей.
 
Как часто обновлять данные
 
Для ежедневных отчётов достаточно одного запуска утром за вчерашний день: к этому времени визиты почти завершены, а нагрузка на сервис минимальна. Частые запросы за сегодня расходуют квоты и дают неполные цифры.