{"name":"API Яндекс Директа v5","vendor":"Яндекс","industry":"marketing","summary":"API рекламной платформы Яндекс Директ (версия 5): управление кампаниями, группами, объявлениями и ключевыми фразами, а также выгрузка статистики через сервис Reports. API состоит из веб-сервисов, у каждого свой URL; методы — обычно `add`, `update`, `delete`, `get` и специфические (например, `moderate` у `Ads`). Подключение бесплатное, нагрузка регулируется баллами.","docsUrl":"https://yandex.ru/dev/direct/doc/ru/","coverage":{"included":[],"excluded":[]},"scenarios":[{"id":"vygruzit-statistiku-reklamnyh-kampaniy","title":"Выгрузить статистику рекламных кампаний","summary":"Расходы, показы, клики и конверсии по дням — в свою аналитику, BI или отчёт клиенту.","steps":["Зарегистрируй приложение и получи 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 должен быть уникальным для разных отчётов: повтор с тем же именем вернёт уже сформированный отчёт."],"code":"import time, requests\n\nheaders = {\"Authorization\": \"Bearer <токен>\", \"processingMode\": \"offline\", \"returnMoneyInMicros\": \"false\",\n           \"skipReportHeader\": \"true\", \"skipReportSummary\": \"true\"}\nbody = {\"params\": {\n    \"SelectionCriteria\": {\"DateFrom\": \"2026-10-01\", \"DateTo\": \"2026-10-23\"},\n    \"FieldNames\": [\"Date\", \"CampaignName\", \"Impressions\", \"Clicks\", \"Cost\"],\n    \"ReportName\": \"campaigns-2026-10-01-23\", \"ReportType\": \"CAMPAIGN_PERFORMANCE_REPORT\",\n    \"DateRangeType\": \"CUSTOM_DATE\", \"Format\": \"TSV\", \"IncludeVAT\": \"YES\"}}\nwhile True:\n    r = requests.post(\"https://api.direct.yandex.com/json/v5/reports\", headers=headers, json=body)\n    if r.status_code == 200:\n        rows = [line.split(\"\\t\") for line in r.text.strip().splitlines()]\n        break\n    if r.status_code in (201, 202):\n        time.sleep(int(r.headers.get(\"retryIn\", 10)))\n        continue\n    raise RuntimeError(r.text)","language":"python","methods":["POST /json/v5/reports"]},{"id":"poluchit-spisok-kampaniy","title":"Получить список кампаний","summary":"Обзор кампаний аккаунта: названия, статусы, состояние — для своей панели управления рекламой.","steps":["Отправь запрос: POST /json/v5/campaigns с method = get и params: SelectionCriteria (пустой — все кампании, или Ids, States, Statuses) и FieldNames — например, Id, Name, State, Status, DailyBudget.","Ответ — result.Campaigns. Метод возвращает не больше 10 000 объектов; если выборка обрезана, придёт LimitedBy — запроси следующую страницу через Page.Offset.","Ошибки уровня запроса приходят с HTTP 200 в объекте error — проверяй его наличие. Расход баллов виден в заголовке Units."],"code":"curl -X POST https://api.direct.yandex.com/json/v5/campaigns \\\n  -H \"Authorization: Bearer $DIRECT_TOKEN\" -H 'Content-Type: application/json; charset=utf-8' \\\n  -d '{\"method\": \"get\", \"params\": {\"SelectionCriteria\": {}, \"FieldNames\": [\"Id\", \"Name\", \"State\", \"Status\"]}}'","language":"bash","methods":["POST /json/v5/campaigns"]},{"id":"sozdat-obyavleniya-v-gruppe","title":"Создать объявления в группе","summary":"Массово завести текстово-графические объявления: под новые товары, акции, города.","steps":["Узнай ID группы объявлений (AdGroupId) — например, из существующих объявлений через Ads.get: POST /json/v5/ads с method = get и SelectionCriteria.CampaignIds.","Создай объявления: Ads.add — POST /json/v5/ads с method = add и params.Ads, где у каждого объявления AdGroupId и TextAd с Title, Text, Href и Mobile = NO.","Результат — в result.AddResults: для каждого объявления Id или Errors. Ошибка одного объявления не отменяет остальные — проверяй каждый элемент.","Ads.add стоит 20 баллов за вызов и 20 за каждое объявление — собирай объявления пачками, а не по одному.","Отлаживай на песочнице https://api-sandbox.direct.yandex.com — данные там удаляются через месяц после последнего обращения."],"code":"curl -X POST https://api.direct.yandex.com/json/v5/ads \\\n  -H \"Authorization: Bearer $DIRECT_TOKEN\" -H 'Content-Type: application/json; charset=utf-8' \\\n  -d '{\"method\": \"add\", \"params\": {\"Ads\": [{\n        \"AdGroupId\": 123456789,\n        \"TextAd\": {\"Title\": \"Кружки с логотипом от 50 шт\", \"Text\": \"Печать за 3 дня. Доставка по России.\", \"Href\": \"https://example.ru/mugs\", \"Mobile\": \"NO\"}\n      }]}}'","language":"bash","methods":["POST /json/v5/ads Ads.get","POST /json/v5/ads Ads.add"]},{"id":"vygruzit-klyuchevye-frazy-kampanii","title":"Выгрузить ключевые фразы кампании","summary":"Аудит семантики: какие фразы есть в кампании, их статусы и ставки.","steps":["Отправь запрос: POST /json/v5/keywords с method = get, SelectionCriteria.CampaignIds (до 10 кампаний) и FieldNames — например, Id, Keyword, AdGroupId, State, Status, Bid.","Поля StatisticsSearch и StatisticsNetwork замедляют ответ — запрашивай их только когда нужны.","Для больших кампаний листай через Page.Limit и Page.Offset."],"code":"curl -X POST https://api.direct.yandex.com/json/v5/keywords \\\n  -H \"Authorization: Bearer $DIRECT_TOKEN\" -H 'Content-Type: application/json; charset=utf-8' \\\n  -d '{\"method\": \"get\", \"params\": {\"SelectionCriteria\": {\"CampaignIds\": [12345678]}, \"FieldNames\": [\"Id\", \"Keyword\", \"AdGroupId\", \"State\", \"Status\"], \"Page\": {\"Limit\": 1000}}}'","language":"bash","methods":["POST /json/v5/keywords"]}],"baseUrls":[{"label":"Боевой","url":"https://api.direct.yandex.com"},{"label":"Тестовый (песочница)","url":"https://api-sandbox.direct.yandex.com"},{"label":"Песочница (SOAP)","url":"https://api-sandbox.direct.yandex.com/v5/{service}"}],"auth":{"type":"oauth2","description":"OAuth 2.0: приложение регистрируется заранее, OAuth-токен пользователя Директа передаётся в заголовке `Authorization: Bearer <токен>`.","example":""},"methods":[{"id":"POST /json/v5/campaigns","title":"Campaigns.get: получение кампаний","httpMethod":"POST","path":"/json/v5/campaigns","description":"Тело: `\"method\": \"get\"` и `params`. Возвращает не больше 10 000 объектов; при обрезке выборки приходит `LimitedBy`.","params":[{"name":"method","in":"body","type":"string","required":true,"description":"get"},{"name":"params.SelectionCriteria.Ids","in":"body","type":"array","required":false,"description":"ID кампаний, до 1000; пустой SelectionCriteria — все кампании"},{"name":"params.SelectionCriteria.Types","in":"body","type":"array","required":false,"description":"Типы кампаний"},{"name":"params.SelectionCriteria.States","in":"body","type":"array","required":false,"description":"Состояния"},{"name":"params.SelectionCriteria.Statuses","in":"body","type":"array","required":false,"description":"Статусы"},{"name":"params.FieldNames","in":"body","type":"array","required":true,"description":"Имена возвращаемых полей кампании"},{"name":"params.Page.Limit","in":"body","type":"integer","required":false,"description":"Размер страницы"},{"name":"params.Page.Offset","in":"body","type":"integer","required":false,"description":"Смещение"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /json/v5/ads Ads.get","title":"Ads.get: получение объявлений","httpMethod":"POST","path":"/json/v5/ads","description":"","params":[{"name":"method","in":"body","type":"string","required":true,"description":"get"},{"name":"params.SelectionCriteria","in":"body","type":"object","required":true,"description":"Нужен хотя бы один из Ids, AdGroupIds, CampaignIds"},{"name":"params.SelectionCriteria.Ids","in":"body","type":"array","required":false,"description":"ID объявлений, до 10 000"},{"name":"params.SelectionCriteria.AdGroupIds","in":"body","type":"array","required":false,"description":"ID групп, до 1000"},{"name":"params.SelectionCriteria.CampaignIds","in":"body","type":"array","required":false,"description":"ID кампаний, до 10"},{"name":"params.FieldNames","in":"body","type":"array","required":true,"description":"Поля верхнего уровня"},{"name":"params.TextAdFieldNames","in":"body","type":"array","required":false,"description":"Поля текстово-графического объявления"},{"name":"params.Page","in":"body","type":"object","required":false,"description":"Limit и Offset"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /json/v5/ads Ads.add","title":"Ads.add: создание объявлений","httpMethod":"POST","path":"/json/v5/ads","description":"Тот же адрес, `\"method\": \"add\"`. В `result.AddResults[]` для каждого объявления — `Id` или `Errors`.","params":[{"name":"method","in":"body","type":"string","required":true,"description":"add"},{"name":"params.Ads","in":"body","type":"array","required":true,"description":"Объявления"},{"name":"params.Ads[].AdGroupId","in":"body","type":"integer","required":true,"description":"ID группы объявлений"},{"name":"params.Ads[].TextAd.Text","in":"body","type":"string","required":false,"description":"Текст текстово-графического объявления"},{"name":"params.Ads[].TextAd.Title","in":"body","type":"string","required":false,"description":"Заголовок"},{"name":"params.Ads[].TextAd.Href","in":"body","type":"string","required":false,"description":"Ссылка"},{"name":"params.Ads[].TextAd.Mobile","in":"body","type":"string","required":false,"description":"Мобильное объявление: YES/NO"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /json/v5/keywords","title":"Keywords.get: получение ключевых фраз","httpMethod":"POST","path":"/json/v5/keywords","description":"","params":[{"name":"method","in":"body","type":"string","required":true,"description":"get"},{"name":"params.SelectionCriteria","in":"body","type":"object","required":true,"description":"Нужен один из Ids, AdGroupIds, CampaignIds"},{"name":"params.SelectionCriteria.Ids","in":"body","type":"array","required":false,"description":"ID фраз и автотаргетингов, до 10 000"},{"name":"params.SelectionCriteria.AdGroupIds","in":"body","type":"array","required":false,"description":"ID групп, до 1000"},{"name":"params.SelectionCriteria.CampaignIds","in":"body","type":"array","required":false,"description":"ID кампаний, до 10"},{"name":"params.FieldNames","in":"body","type":"array","required":true,"description":"Возвращаемые поля; StatisticsSearch и StatisticsNetwork замедляют большие выборки"},{"name":"params.Page","in":"body","type":"object","required":false,"description":"Limit и Offset"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /json/v5/reports","title":"Reports: отчёт статистики","httpMethod":"POST","path":"/json/v5/reports","description":"Тело — `params` (ReportDefinition); ответ — отчёт в формате TSV. В режиме offline отчёт формируется асинхронно, заголовок ответа `retryIn` подсказывает интервал повторного запроса в секундах.","params":[{"name":"processingMode","in":"header","type":"string","required":false,"description":"online, offline или auto (по умолчанию)"},{"name":"returnMoneyInMicros","in":"header","type":"string","required":false,"description":"false — деньги в валюте с двумя знаками; по умолчанию × 1 000 000"},{"name":"skipReportHeader","in":"header","type":"string","required":false,"description":"true — без строки с названием отчёта"},{"name":"skipColumnHeader","in":"header","type":"string","required":false,"description":"true — без строки с названиями полей"},{"name":"skipReportSummary","in":"header","type":"string","required":false,"description":"true — без строки с числом строк"},{"name":"params.SelectionCriteria","in":"body","type":"object","required":true,"description":"Критерии отбора; DateFrom/DateTo — только при CUSTOM_DATE, Filter — необязательный"},{"name":"params.FieldNames","in":"body","type":"array","required":true,"description":"Поля отчёта"},{"name":"params.ReportName","in":"body","type":"string","required":true,"description":"Название отчёта"},{"name":"params.ReportType","in":"body","type":"string","required":true,"description":"Тип отчёта, например ACCOUNT_PERFORMANCE_REPORT"},{"name":"params.DateRangeType","in":"body","type":"string","required":true,"description":"Период, например CUSTOM_DATE"},{"name":"params.Format","in":"body","type":"string","required":true,"description":"Только TSV"},{"name":"params.IncludeVAT","in":"body","type":"string","required":true,"description":"Учитывать НДС: YES/NO"},{"name":"params.Goals","in":"body","type":"array","required":false,"description":"Цели"},{"name":"params.AttributionModels","in":"body","type":"array","required":false,"description":"Модели атрибуции"},{"name":"params.Page.Limit","in":"body","type":"integer","required":false,"description":"Ограничение строк (обязательно внутри Page)"},{"name":"params.OrderBy","in":"body","type":"array","required":false,"description":"Сортировка"}],"requestExample":"","responseExample":"","docsUrl":""}],"codeExamples":[],"errors":[{"code":"52","description":"Сервер авторизации временно недоступен — повторите позже"},{"code":"53","description":"Ошибка авторизации: недействительный OAuth-токен"},{"code":"54","description":"Нет прав"},{"code":"152","description":"Недостаточно баллов"},{"code":"506","description":"Превышено ограничение на число одновременных соединений"},{"code":"513","description":"Логин не подключён к Яндекс Директу"},{"code":"1000","description":"Внутренняя ошибка сервера API"},{"code":"1002","description":"Ошибка операции"},{"code":"3000","description":"Нет доступа к API"},{"code":"3001","description":"Нет доступа к методу"},{"code":"4000","description":"Неверно указаны параметры запроса"},{"code":"8000","description":"Некорректный запрос (нет токена, обязательного параметра, невалидный JSON)"},{"code":"8800","description":"Объект не найден"}],"limits":"- Не больше 5 одновременных запросов от одного рекламодателя.\n- Суточный лимит баллов индивидуален и делится на 24 часовых интервала со скользящим окном.\n- Стоимость: ошибка вызова — 20 баллов; `Campaigns.get` — 10 за вызов и 1 за объект; `Ads.add` — 20 за вызов и 20 за объект; `Dictionaries.get` — 1 балл.\n- Методы `get` возвращают не больше 10 000 объектов.","gotchas":["Все запросы — 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/`.","В песочнице действуют те же ограничения; данные удаляются через месяц после последнего обращения."],"slug":"yandex-direct","version":2,"updatedAt":"2026-10-24T17:05:40.190Z","sources":[{"title":"Общая структура API","url":"https://yandex.ru/dev/direct/doc/ru/concepts/overview","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Формат JSON","url":"https://yandex.ru/dev/direct/doc/ru/concepts/json","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"HTTP-заголовки","url":"https://yandex.ru/dev/direct/doc/ru/concepts/headers","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Песочница","url":"https://yandex.ru/dev/direct/doc/en/concepts/sandbox","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Ограничения, баллы","url":"https://yandex.ru/dev/direct/doc/ru/concepts/units","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Campaigns.get","url":"https://yandex.ru/dev/direct/doc/ru/campaigns/get","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Ads.get","url":"https://yandex.ru/dev/direct/doc/ru/ads/get","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Keywords.get","url":"https://yandex.ru/dev/direct/doc/ru/keywords/get","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Reports — спецификация отчёта","url":"https://yandex.ru/dev/direct/doc/ru/spec","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Reports — HTTP-заголовки","url":"https://yandex.ru/dev/direct/doc/en/headers","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Коды ошибок","url":"https://yandex.ru/dev/direct/doc/ru/concepts/errors-list","kind":"research","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"Вставленный текст","url":"","kind":"import","addedAt":"2026-10-14T14:52:43.795Z"},{"title":"scenarios-yandex-direct.md","url":"","kind":"import","addedAt":"2026-10-24T17:05:29.599Z"}],"logoUrl":null}