API Яндекс Директа v5 API

Отрасль: Реклама и аналитика. Актуально на 2026-10-24.

API рекламной платформы Яндекс Директ (версия 5): управление кампаниями, группами, объявлениями и ключевыми фразами, а также выгрузка статистики через сервис Reports. API состоит из веб-сервисов, у каждого свой URL; методы — обычно add, update, delete, get и специфические (например, moderate у Ads). Подключение бесплатное, нагрузка регулируется баллами.

Сценарии

Выгрузить статистику рекламных кампаний

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

1. Зарегистрируй приложение и получи OAuth-токен пользователя Директа; передавай его в заголовке Authorization: Bearer <токен>. Для агентского аккаунта добавляй заголовок Client-Login с логином клиента.
2. Запроси отчёт: 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.
3. В режиме processingMode = offline отчёт готовится асинхронно: ответ 201 или 202 значит «ещё не готов» — повтори тот же запрос через retryIn секунд из заголовка. Ответ 200 — тело с отчётом в TSV.
4. Деньги по умолчанию умножены на 1 000 000 — передай заголовок returnMoneyInMicros: false, чтобы получать рубли с копейками. skipReportHeader и skipReportSummary убирают служебные строки.
5. 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)

Получить список кампаний

Обзор кампаний аккаунта: названия, статусы, состояние — для своей панели управления рекламой.

1. Отправь запрос: POST /json/v5/campaigns с method = get и params: SelectionCriteria (пустой — все кампании, или Ids, States, Statuses) и FieldNames — например, Id, Name, State, Status, DailyBudget.
2. Ответ — result.Campaigns. Метод возвращает не больше 10 000 объектов; если выборка обрезана, придёт LimitedBy — запроси следующую страницу через Page.Offset.
3. Ошибки уровня запроса приходят с HTTP 200 в объекте error — проверяй его наличие. Расход баллов виден в заголовке Units.

curl -X POST https://api.direct.yandex.com/json/v5/campaigns \
  -H "Authorization: Bearer $DIRECT_TOKEN" -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"method": "get", "params": {"SelectionCriteria": {}, "FieldNames": ["Id", "Name", "State", "Status"]}}'

Создать объявления в группе

Массово завести текстово-графические объявления: под новые товары, акции, города.

1. Узнай ID группы объявлений (AdGroupId) — например, из существующих объявлений через Ads.get: POST /json/v5/ads с method = get и SelectionCriteria.CampaignIds.
2. Создай объявления: Ads.add — POST /json/v5/ads с method = add и params.Ads, где у каждого объявления AdGroupId и TextAd с Title, Text, Href и Mobile = NO.
3. Результат — в result.AddResults: для каждого объявления Id или Errors. Ошибка одного объявления не отменяет остальные — проверяй каждый элемент.
4. Ads.add стоит 20 баллов за вызов и 20 за каждое объявление — собирай объявления пачками, а не по одному.
5. Отлаживай на песочнице https://api-sandbox.direct.yandex.com — данные там удаляются через месяц после последнего обращения.

curl -X POST https://api.direct.yandex.com/json/v5/ads \
  -H "Authorization: Bearer $DIRECT_TOKEN" -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"method": "add", "params": {"Ads": [{
        "AdGroupId": 123456789,
        "TextAd": {"Title": "Кружки с логотипом от 50 шт", "Text": "Печать за 3 дня. Доставка по России.", "Href": "https://example.ru/mugs", "Mobile": "NO"}
      }]}}'

Выгрузить ключевые фразы кампании

Аудит семантики: какие фразы есть в кампании, их статусы и ставки.

1. Отправь запрос: POST /json/v5/keywords с method = get, SelectionCriteria.CampaignIds (до 10 кампаний) и FieldNames — например, Id, Keyword, AdGroupId, State, Status, Bid.
2. Поля StatisticsSearch и StatisticsNetwork замедляют ответ — запрашивай их только когда нужны.
3. Для больших кампаний листай через Page.Limit и Page.Offset.

curl -X POST https://api.direct.yandex.com/json/v5/keywords \
  -H "Authorization: Bearer $DIRECT_TOKEN" -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"method": "get", "params": {"SelectionCriteria": {"CampaignIds": [12345678]}, "FieldNames": ["Id", "Keyword", "AdGroupId", "State", "Status"], "Page": {"Limit": 1000}}}'

Базовые 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/campaigns — Campaigns.get: получение кампаний

Тело: "method": "get" и params. Возвращает не больше 10 000 объектов; при обрезке выборки приходит LimitedBy.

Параметр	Где	Тип	Обяз.	Описание
method	body	string	да	get
params.SelectionCriteria.Ids	body	array	нет	ID кампаний, до 1000; пустой SelectionCriteria — все кампании
params.SelectionCriteria.Types	body	array	нет	Типы кампаний
params.SelectionCriteria.States	body	array	нет	Состояния
params.SelectionCriteria.Statuses	body	array	нет	Статусы
params.FieldNames	body	array	да	Имена возвращаемых полей кампании
params.Page.Limit	body	integer	нет	Размер страницы
params.Page.Offset	body	integer	нет	Смещение

POST /json/v5/ads — Ads.get: получение объявлений

Параметр	Где	Тип	Обяз.	Описание
method	body	string	да	get
params.SelectionCriteria	body	object	да	Нужен хотя бы один из Ids, AdGroupIds, CampaignIds
params.SelectionCriteria.Ids	body	array	нет	ID объявлений, до 10 000
params.SelectionCriteria.AdGroupIds	body	array	нет	ID групп, до 1000
params.SelectionCriteria.CampaignIds	body	array	нет	ID кампаний, до 10
params.FieldNames	body	array	да	Поля верхнего уровня
params.TextAdFieldNames	body	array	нет	Поля текстово-графического объявления
params.Page	body	object	нет	Limit и Offset

POST /json/v5/ads — Ads.add: создание объявлений

Тот же адрес, "method": "add". В result.AddResults[] для каждого объявления — Id или Errors.

Параметр	Где	Тип	Обяз.	Описание
method	body	string	да	add
params.Ads	body	array	да	Объявления
params.Ads[].AdGroupId	body	integer	да	ID группы объявлений
params.Ads[].TextAd.Text	body	string	нет	Текст текстово-графического объявления
params.Ads[].TextAd.Title	body	string	нет	Заголовок
params.Ads[].TextAd.Href	body	string	нет	Ссылка
params.Ads[].TextAd.Mobile	body	string	нет	Мобильное объявление: YES/NO

POST /json/v5/keywords — Keywords.get: получение ключевых фраз

Параметр	Где	Тип	Обяз.	Описание
method	body	string	да	get
params.SelectionCriteria	body	object	да	Нужен один из Ids, AdGroupIds, CampaignIds
params.SelectionCriteria.Ids	body	array	нет	ID фраз и автотаргетингов, до 10 000
params.SelectionCriteria.AdGroupIds	body	array	нет	ID групп, до 1000
params.SelectionCriteria.CampaignIds	body	array	нет	ID кампаний, до 10
params.FieldNames	body	array	да	Возвращаемые поля; StatisticsSearch и StatisticsNetwork замедляют большие выборки
params.Page	body	object	нет	Limit и Offset

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/.
• В песочнице действуют те же ограничения; данные удаляются через месяц после последнего обращения.

Ошибки

Код	Описание
52	Сервер авторизации временно недоступен — повторите позже
53	Ошибка авторизации: недействительный OAuth-токен
54	Нет прав
152	Недостаточно баллов
506	Превышено ограничение на число одновременных соединений
513	Логин не подключён к Яндекс Директу
1000	Внутренняя ошибка сервера API
1002	Ошибка операции
3000	Нет доступа к API
3001	Нет доступа к методу
4000	Неверно указаны параметры запроса
8000	Некорректный запрос (нет токена, обязательного параметра, невалидный JSON)
8800	Объект не найден

Ограничения

• Не больше 5 одновременных запросов от одного рекламодателя.
• Суточный лимит баллов индивидуален и делится на 24 часовых интервала со скользящим окном.
• Стоимость: ошибка вызова — 20 баллов; Campaigns.get — 10 за вызов и 1 за объект; Ads.add — 20 за вызов и 20 за объект; Dictionaries.get — 1 балл.
• Методы get возвращают не больше 10 000 объектов.

Источники

• Общая структура API
• Формат JSON
• HTTP-заголовки
• Песочница
• Ограничения, баллы
• Campaigns.get
• Ads.get
• Keywords.get
• Reports — спецификация отчёта
• Reports — HTTP-заголовки
• Коды ошибок

---

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