API Яндекс Директа v5: Выгрузить статистику рекламных кампаний

Сценарий из mcp-everything. Актуально на 2026-10-24.

Расходы, показы, клики и конверсии по дням — в свою аналитику, BI или отчёт клиенту.

Зарегистрируй приложение и получи OAuth-токен пользователя Директа; передавай его в заголовке Authorization: Bearer <токен>. Для агентского аккаунта добавляй заголовок Client-Login с логином клиента.
Запроси отчёт: POST /json/v5/reports с params — ReportDefinition: SelectionCriteria (DateFrom, DateTo), FieldNames (Date, CampaignName, Impressions, Clicks, Cost), ReportName, ReportType (например, CAMPAIGN_PERFORMANCE_REPORT), DateRangeType = CUSTOM_DATE, Format = TSV, IncludeVAT.
В режиме processingMode = offline отчёт готовится асинхронно: ответ 201 или 202 значит «ещё не готов» — повтори тот же запрос через retryIn секунд из заголовка. Ответ 200 — тело с отчётом в TSV.
Деньги по умолчанию умножены на 1 000 000 — передай заголовок returnMoneyInMicros: false, чтобы получать рубли с копейками. skipReportHeader и skipReportSummary убирают служебные строки.
ReportName должен быть уникальным для разных отчётов: повтор с тем же именем вернёт уже сформированный отчёт.

import time, requests

headers = {"Authorization": "Bearer <токен>", "processingMode": "offline", "returnMoneyInMicros": "false",
           "skipReportHeader": "true", "skipReportSummary": "true"}
body = {"params": {
    "SelectionCriteria": {"DateFrom": "2026-10-01", "DateTo": "2026-10-23"},
    "FieldNames": ["Date", "CampaignName", "Impressions", "Clicks", "Cost"],
    "ReportName": "campaigns-2026-10-01-23", "ReportType": "CAMPAIGN_PERFORMANCE_REPORT",
    "DateRangeType": "CUSTOM_DATE", "Format": "TSV", "IncludeVAT": "YES"}}
while True:
    r = requests.post("https://api.direct.yandex.com/json/v5/reports", headers=headers, json=body)
    if r.status_code == 200:
        rows = [line.split("\t") for line in r.text.strip().splitlines()]
        break
    if r.status_code in (201, 202):
        time.sleep(int(r.headers.get("retryIn", 10)))
        continue
    raise RuntimeError(r.text)

Базовые URL

Боевой: https://api.direct.yandex.com
Тестовый (песочница): https://api-sandbox.direct.yandex.com
Песочница (SOAP): https://api-sandbox.direct.yandex.com/v5/{service}

Авторизация

Тип: OAuth 2.0

OAuth 2.0: приложение регистрируется заранее, OAuth-токен пользователя Директа передаётся в заголовке Authorization: Bearer <токен>.

Методы сценария

POST /json/v5/reports — Reports: отчёт статистики

Тело — params (ReportDefinition); ответ — отчёт в формате TSV. В режиме offline отчёт формируется асинхронно, заголовок ответа retryIn подсказывает интервал повторного запроса в секундах.

Параметр	Где	Тип	Обяз.	Описание
`processingMode`	header	string	нет	online, offline или auto (по умолчанию)
`returnMoneyInMicros`	header	string	нет	false — деньги в валюте с двумя знаками; по умолчанию × 1 000 000
`skipReportHeader`	header	string	нет	true — без строки с названием отчёта
`skipColumnHeader`	header	string	нет	true — без строки с названиями полей
`skipReportSummary`	header	string	нет	true — без строки с числом строк
`params.SelectionCriteria`	body	object	да	Критерии отбора; DateFrom/DateTo — только при CUSTOM_DATE, Filter — необязательный
`params.FieldNames`	body	array	да	Поля отчёта
`params.ReportName`	body	string	да	Название отчёта
`params.ReportType`	body	string	да	Тип отчёта, например ACCOUNT_PERFORMANCE_REPORT
`params.DateRangeType`	body	string	да	Период, например CUSTOM_DATE
`params.Format`	body	string	да	Только TSV
`params.IncludeVAT`	body	string	да	Учитывать НДС: YES/NO
`params.Goals`	body	array	нет	Цели
`params.AttributionModels`	body	array	нет	Модели атрибуции
`params.Page.Limit`	body	integer	нет	Ограничение строк (обязательно внутри Page)
`params.OrderBy`	body	array	нет	Сортировка

Нюансы

Все запросы — HTTPS POST; в теле JSON всегда есть method и, как правило, params. Поддерживается и SOAP/XML.
Ошибки уровня запроса приходят с HTTP 200 в объекте error (request_id, error_code, error_string, error_detail) — проверяйте наличие error, а не только статус.
Ошибки отдельных объектов при add/update возвращаются в Errors соответствующего элемента результата.
Заголовки ответа: RequestId (указывать в обращениях в поддержку), Units (списано/остаток/суточный лимит, например 10/20828/64000), Units-Used-Login.
Денежные значения в фильтрах Reports — целые числа, умноженные на 1 000 000.
Товарные объявления работают через адрес https://api.direct.yandex.com/v501/.
В песочнице действуют те же ограничения; данные удаляются через месяц после последнего обращения.

Другие сценарии

Если этого недостаточно — официальная документация: https://yandex.ru/dev/direct/doc/ru/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandex-direct.md