Reports API Яндекс Директа: SearchQueryReport, CUSTOM_REPORT

Reports API Яндекс Директа — асинхронная выгрузка статистики в TSV/CSV.

Коротко: POST https://api.direct.yandex.com/json/v5/reports; асинхронная выгрузка 200/201/202.

← Каталог API Директа · Введение · Версии API · OAuth и доступ · Сервисы v5 · Лимиты и баллы · Ограничения · Кампании · Группы и объявления · Ключи и ставки · Минус-фразы и площадки · Песочница · Агентства · Примеры JSON · Ошибки · Автоматизация · Документация Яндекса

Содержание

  1. Endpoint
  2. Асинхронный workflow
  3. Типы отчётов
  4. SearchQueryReport
  5. CUSTOM_REPORT
  6. Советы

Endpoint и заголовки

POST https://api.direct.yandex.com/json/v5/reports

Authorization: Bearer <token>

Client-Login: <client-login>

Accept-Language: ru

Content-Type: application/json; charset=utf-8

{

  "params": {

    "SelectionCriteria": {},

    "FieldNames": ["CampaignId", "CampaignName", "Clicks", "Cost", "Impressions"],

    "ReportName": "campaign_stats_2026_08",

    "ReportType": "CAMPAIGN_PERFORMANCE_REPORT",

    "DateRangeType": "LAST_30_DAYS",

    "Format": "TSV",

    "IncludeVAT": "YES",

    "IncludeDiscount": "NO"

  }

}

Асинхронный workflow

HTTP-кодЗначениеДействие
200Отчёт готовТело ответа — TSV/CSV данные
201Отчёт в очередиПовторить через retry-in секунд
202ФормируетсяПовторить через retry-in секунд
400/500ОшибкаРазобрать JSON error

Алгоритм:

  1. POST запрос с уникальным ReportName.
  2. Если 201/202 — подождать retry-in секунд (из заголовка) и повторить тот же запрос.
  3. При 200 — сохранить TSV, парсить (первая строка — заголовки).
  4. Не запрашивайте новый отчёт, пока предыдущий не готов (ошибка 400).

Типы отчётов

ReportTypeНазначениеКлючевые поля
CAMPAIGN_PERFORMANCE_REPORTСтатистика по кампаниямCampaignId, Clicks, Cost, Impressions
ADGROUP_PERFORMANCE_REPORTПо группамAdGroupId, AdGroupName, Clicks, Cost
AD_PERFORMANCE_REPORTПо объявлениямAdId, Clicks, Cost, AvgCpc
CRITERIA_PERFORMANCE_REPORTПо ключевым фразамCriterion, Clicks, Cost, AvgCpc
SEARCH_QUERY_PERFORMANCE_REPORTПоисковые запросыQuery, Clicks, Cost, Conversions
CUSTOM_REPORTГибкий отчётЛюбой набор полей
REACH_AND_FREQUENCY_REPORTReach & FrequencyОхват и частота (CPM)
ACCOUNT_PERFORMANCE_REPORTПо аккаунтуСводная статистика

SEARCH_QUERY_PERFORMANCE_REPORT

{"params":{"SelectionCriteria":{"Filter":[{"Field":"Clicks","Operator":"GREATER_THAN","Values":["0"]}]},"FieldNames":["Query","CampaignName","Clicks","Cost","Conversions"],"ReportName":"sq_report_aug","ReportType":"SEARCH_QUERY_PERFORMANCE_REPORT","DateRangeType":"LAST_30_DAYS","Format":"TSV"}}

Основной отчёт для массовой минусовки и анализа поисковых запросов.

CUSTOM_REPORT

Гибкий отчёт позволяет выбрать любые совместимые поля и фильтры. Укажите ReportType: CUSTOM_REPORT и набор FieldNames из справочника полей отчётов.

Советы по Reports API

  • Используйте уникальный ReportName для каждого запроса.
  • Для агентств — заголовок Client-Login.
  • Большие отчёты запускайте ночью — меньше конкуренции.
  • Учитывайте баллы: Лимиты.

← Каталог API Директа · Введение · Версии API · OAuth и доступ · Сервисы v5 · Лимиты и баллы · Ограничения · Кампании · Группы и объявления · Ключи и ставки · Минус-фразы и площадки · Песочница · Агентства · Примеры JSON · Ошибки · Автоматизация

Перейти в инструмент