| name | direct-eda |
| description | Разведочный анализ (EDA) статистики Яндекс.Директ поверх отчётов. Используется когда пользователь просит проанализировать статистику/данные, найти тренды или аномалии, построить разрез по времени/устройствам/гео/полу-возрасту, выбрать топ/антитоп кампаний, ключей или объявлений, оценить эффективность (CTR, CR, CPA, ROAS) и дать выводы/рекомендации. |
| user-invocable | true |
| argument-hint | [что анализируем: период, разрез, метрика — напр. «расход по месяцам за год» или «топ-20 ключей по CPA»] |
Разведочный анализ статистики Яндекс.Директ (EDA)
Скилл для исследования статистики кампаний через отчётные MCP-инструменты плагина.
Не вводит новых API-методов — это композиция reports_get / reports_custom /
reports_list_types (+ v4goals_get_stat_goals для целей) с правильным выбором
разреза, метрик и подачи выводов.
С чего начинать
- Авторизация. Сначала
auth_status(). Если valid: false — auth_login().
Без авторизации отчёты вернут ошибку.
- Выбор инструмента:
reports_get(date_from, date_to) — быстрый снимок по кампаниям за короткое
окно (по умолчанию ~8 дней, дефолтные поля). Для ответа «как там кампании».reports_custom(field_names=…) — всё остальное: произвольные поля, разрезы
по времени/срезам, фильтры, сортировка, цели, пагинация, выгрузка в файл.reports_list_types() — если не уверен, какой report_type подходит.
- Сомневаешься в полях/фильтрах —
dry_run=True. Reports API отвергает
неверные enum'ы опаковым error_code=8000; локальный dry-run экономит раунд-трип
и показывает итоговый request_body.
Типовые рецепты EDA
report_type по умолчанию = CUSTOM_REPORT (самый широкий набор измерений).
Деньги по умолчанию в рублях (не микро). field_names — регистрозависимый enum.
| Вопрос | Как получить |
|---|
| Общий снимок по кампаниям | reports_get() (или reports_custom с CampaignName,Impressions,Clicks,Cost,Conversions,Ctr,AvgCpc) |
| Динамика по месяцам/неделям/дням | field_names="Month,Cost,Clicks,Conversions,…", order_by=["Month:ASC"] (или Week/Date) |
| Топ-N кампаний по расходу/конверсиям | field_names="CampaignName,Cost,Clicks,Conversions,CostPerConversion", order_by=["Cost:DESC"], page_limit=N |
| Топ-N ключевых фраз | report_type="CRITERIA_PERFORMANCE_REPORT", field_names="CampaignName,Criterion,Clicks,Cost,Ctr,Conversions", order_by=["Cost:DESC"], page_limit=N |
| Разрез по устройствам | field_names="Device,Cost,Clicks,Ctr,Conversions,CostPerConversion" |
| Разрез по площадкам (Поиск/Сети) | field_names="AdNetworkType,Cost,Clicks,Ctr,Conversions" |
| Пол / возраст | field_names="Gender,Age,Impressions,Clicks,Ctr,Conversions" |
| География | field_names="LocationOfPresenceName,Cost,Clicks,Conversions" (или TargetingLocationName) |
| Поисковые запросы (для минус-слов / новых ключей) | report_type="SEARCH_QUERY_PERFORMANCE_REPORT", field_names="Query,Impressions,Clicks,Ctr,Cost,Conversions", order_by=["Cost:DESC"] |
| Конверсии по целям Метрики | задай goal_ids="123,456" → в выводе появятся Conversions_<goal>_<attr> и CostPerConversion_<goal>_<attr>. ID целей: v4goals_get_stat_goals(campaign_ids=…) |
| Итоги по всему аккаунту | report_type="ACCOUNT_PERFORMANCE_REPORT" |
Период: либо date_from/date_to (YYYY-MM-DD), либо пресет date_range_type
(last_7_days, last_30_days, last_3_months, last_week, last_5_years, …) —
одно из двух, не вместе. Для «за 2 года» передавай явные даты (пресета
last_2_years нет).
Метрики и производные KPI
Базовые поля API: Impressions, Clicks, Cost, Ctr, AvgCpc, Conversions,
ConversionRate, CostPerConversion, Revenue, BounceRate, AvgPageviews,
AvgImpressionPosition. Чего нет в API — считай сам из выгрузки:
- CTR = Clicks / Impressions; CR = Conversions / Clicks;
- CPC = Cost / Clicks; CPA (CPL) = Cost / Conversions;
- ROAS = Revenue / Cost; CRR = Cost / Revenue (доля рекламных расходов);
- доля расхода кампании = Cost_i / Σ Cost.
Берёшь сырые Impressions/Clicks/Cost/Conversions/Revenue нужным разрезом и
агрегируешь/делишь на стороне анализа — так точнее, чем доверять предсчитанным
полям на мелких выборках (деление на ноль, округления).
Поиск аномалий (что искать)
- Скачки расхода: динамика
Cost по Date/Week — всплески/обвалы > N% к
соседнему периоду или к скользящему среднему.
- Падение эффективности: рост
CostPerConversion / падение ConversionRate
или Ctr период-к-периоду (сравни два окна одинаковой длины).
- Расход без конверсий: строки с
Cost>0 и Conversions=0 (фильтр
["Clicks:GREATER_THAN:0"], затем смотри нулевые конверсии) — кандидаты в стоп
или в минус-слова (через SEARCH_QUERY_PERFORMANCE_REPORT).
- Концентрация: 80/20 — какие кампании/ключи дают основной расход и
основную конверсию (часто это разные множества).
- Аномальные срезы: устройство/гео/демография с CPA в разы выше среднего.
Для сравнения «период к периоду» делай два запроса с равными окнами (напр.
last_7_days и предыдущая неделя явными датами) и считай дельты.
Большие выгрузки и подача
- Большой отчёт (>5k строк или > ~6 мес):
output_path="/tmp/…json" —
инструмент вернёт {output_path, rows_written, …}, дальше читай файл обычными
файловыми инструментами и анализируй локально. Допустимые корни пути — системный
temp или $CLAUDE_PLUGIN_DATA.
- Формат:
response_format="json" (по умолчанию, удобно для разбора) или
csv/tsv/table.
- Подача вывода пользователю: сначала короткий вывод (1–3 факта/инсайта),
затем таблица с числами, затем конкретные рекомендации к действию (что усилить,
что остановить, где добавить минус-слова/скорректировать ставки). Цифры приводи
с единицами (₽, %, шт.) и за какой период.
Подводные камни
- Цели — только через
goal_ids, не через filters (Goals:-фильтр API не
поддерживает; инструмент его отклонит).
filters перекрывают campaign_ids/adgroup_ids (direct-cli применит
фильтры и проигнорирует селекторы). Нужен и срез по кампаниям, и фильтр — вырази
кампании фильтром: ["CampaignId:IN:111,222"].field_names — регистрозависимый enum, зависящий от report_type. Не уверен —
dry_run=True или reports_list_types().campaign_ids/adgroup_ids/goal_ids — ≤10 на запрос.- Атрибуция: дефолтный код в per-goal колонках —
LSC; нужен другой — задай
attribution_models (FC,LC,LSC,LYDC,…).
- НДС/скидка:
include_vat/include_discount берут настройку аккаунта, если не
заданы явно — учитывай при сравнении «расхода» с биллингом.
Связанные навыки
- Управление сущностями (создать/изменить кампании, ставки и т.п.) — навык
yandex-direct.
- Написание текстов объявлений по итогам анализа — навык
direct-ads.
