---
slug: "yandex-direct"
name: "API Яндекс Директа v5"
vendor: "Яндекс"
industry: "marketing"
docsUrl: "https://yandex.ru/dev/direct/doc/ru/"
version: 2
updatedAt: "2026-10-24"
---

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

Отрасль: Реклама и аналитика. Актуально на 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 должен быть уникальным для разных отчётов: повтор с тем же именем вернёт уже сформированный отчёт.

```python
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.

```bash
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 — данные там удаляются через месяц после последнего обращения.

```bash
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.

```bash
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](https://yandex.ru/dev/direct/doc/ru/concepts/overview)
- [Формат JSON](https://yandex.ru/dev/direct/doc/ru/concepts/json)
- [HTTP-заголовки](https://yandex.ru/dev/direct/doc/ru/concepts/headers)
- [Песочница](https://yandex.ru/dev/direct/doc/en/concepts/sandbox)
- [Ограничения, баллы](https://yandex.ru/dev/direct/doc/ru/concepts/units)
- [Campaigns.get](https://yandex.ru/dev/direct/doc/ru/campaigns/get)
- [Ads.get](https://yandex.ru/dev/direct/doc/ru/ads/get)
- [Keywords.get](https://yandex.ru/dev/direct/doc/ru/keywords/get)
- [Reports — спецификация отчёта](https://yandex.ru/dev/direct/doc/ru/spec)
- [Reports — HTTP-заголовки](https://yandex.ru/dev/direct/doc/en/headers)
- [Коды ошибок](https://yandex.ru/dev/direct/doc/ru/concepts/errors-list)

---

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