Интеграции

Отчёты и статистика

Обновлено 25 октября 2026

С какого отчёта начать

Инструмент	Для чего использовать	Период / число строк по умолчанию
`direct_get_campaign_stats`	Сравнить кампании по показам, кликам, CTR, расходу и средней цене клика. `by_date: true` включает разбивку по дням.	`LAST_30_DAYS` / 100
`direct_get_keyword_stats`	Разобрать условия показа, среднюю ставку с корректировками и объём трафика.	`LAST_30_DAYS` / 100
`direct_get_search_queries`	Сопоставить реальные запросы пользователей с фразами.	`LAST_7_DAYS` / 200
`direct_query_report`	Получить дополнительные срезы по устройствам, регионам, площадкам и другим полям API.	`LAST_30_DAYS` / 100

Для выбранных кампаний передавайте campaign_ids в готовые отчёты. У произвольного отчёта отбор задаётся через filters.

Период

Аргумент period принимает именованный период, например TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH или LAST_MONTH.

Для своего периода передайте date_from и date_to в формате YYYY-MM-DD. Переданные даты имеют приоритет над period. Если указана только начальная дата, конечной станет текущая дата сервера. Если указана только конечная, начало рассчитывается за 29 дней до неё.

Поисковые запросы доступны в пределах последних 180 дней по ограничению Директа; за слишком ранний период API может вернуть отказ.

Конверсии и цели Метрики

Чтобы готовые отчёты включали показатели конверсий, передайте goals — список номеров целей Метрики, не более десяти. Модель атрибуции задаётся аргументом attribution:

Значение	Смысл
`LSCCD`	Последний значимый переход кросс-девайс; по умолчанию.
`FCCD`	Первый переход кросс-девайс.
`LC`	Последний переход.
`AUTO`	Автоматическая модель.

Столбцы получают имена вида Conversions_<цель>_<модель> и CostPerConversion_<цель>_<модель>. Номера целей нужно знать заранее; отдельного инструмента получения списка целей Метрики у этого плагина нет.

Пример просьбы:

Сравни кампании за прошлый месяц по расходу и конверсиям
для согласованных целей Метрики. Укажи модель атрибуции
и не называй конверсии заказами без проверки смысла целей.

Расход и конверсии по условиям показа В ответе агента сопоставлены показы, клики, CTR, расход и конверсии фраз и автотаргетинга.

Деньги и НДС

Ставки, бюджеты и денежные показатели возвращаются в обычных единицах валюты аккаунта. Проверяйте валюту через direct_get_account; суммы не обязательно выражены в рублях.

Учёт НДС для отчётов задаётся настройкой «НДС в суммах отчётов».

Есть исключение для разработчика: в direct_query_report денежные значения внутри filters[].values передаются в единицах API, умноженными на 1 000 000. Например, порог 100 единиц валюты в денежном фильтре записывается строкой "100000000". Не переносите это правило на аргументы ставок и бюджетов.

Очередь формирования

Если Директ не успел подготовить отчёт, плагин возвращает:

ok: false
error_code: report_pending
retry_in: время до следующей попытки

Повторите тот же вызов с теми же аргументами после указанного ожидания. Так плагин подхватит уже заказанный отчёт. Изменение параметров создаст другой запрос отчёта.

Постраничность и полнота данных

Используйте limit и offset; смещение начинается с нуля. Для отчётов допустимо до 10 000 строк на страницу. Возвращённые row_count и rows относятся к полученной выдаче.

Поле totals, когда оно есть, вычисляется по возвращённым строкам. Это не гарантированный итог всего аккаунта при ограничении числа строк. Для полного анализа нужно получить остальные страницы и учесть тот же отбор.

В объектных списках limited_by, если оно вернулось, указывает на ограничение ответа API. Максимумы и значения по умолчанию у разных инструментов различаются: используйте их схемы из MCP.

Запросы расходуют баллы API. При малом остатке плагин добавляет units_warning; при исчерпании может вернуть units_exhausted. Сужайте период и список кампаний, когда полный отчёт не нужен.

Для разработчика

Длинные идентификаторы объявлений и фраз передавайте строками: JSON-числа в JavaScript могут потерять точность. Схемы идентификаторов поддерживают целое число или строку с цифрами.

Обычная ошибка инструмента содержит ok: false, error_code и error_message; при наличии добавляется request_id. Сохраните эти сведения для разбора отказа API.