Частые вопросы

Почему список проектов в настройках пустой или показывает ошибку?

Сначала сохраните «User-Id Топвизора» и «API-ключ», затем снова откройте настройки. Список строится по сохранённым значениям. User-Id должен состоять из цифр; ключ нужно скопировать целиком без внутренних пробелов, переносов и кириллицы.

При not_configured проверьте заполнение и формат реквизитов. При auth_failed Топвизор не принял их. При network_error проверьте исходящий HTTPS с сервера к api.topvisor.com. Если проектов нет в самом аккаунте, форма сообщает об этом. Список в настройках кешируется на 10 минут.

Почему агент не видит инструмент или получает отказ в доступе к проекту?

Проверьте права используемого токена MCP в группе «Топвизор»: право каждого инструмента выдаётся отдельно. Для запуска нужно право на конкретный *_check_run, для изменения — право на соответствующий инструмент записи.

Ошибка access_denied от API относится к доступу настроенного пользователя Топвизора: проект может быть чужим или доступ к нему ограничен. Сверьте project_id через topvisor_projects_list. Права токена MCP не расширяют права пользователя Топвизора.

Почему плагин требует project_id, если проект выбран в настройках?

Проект по умолчанию используется в читающих инструментах, где project_id необязателен. Для записи в существующий проект, расчёта стоимости и платного запуска проект передаётся явно. Это предотвращает действия в случайно выбранном проекте. Возьмите идентификатор из topvisor_projects_list.

Почему нет позиций или часть периода отсутствует?

Чтение возвращает результаты уже сделанных съёмов и не запускает новый. Проверьте выбранный проект, регион и фактические даты съёмов. region_index нужно брать из topvisor_project_searchers_regions, а не подставлять номер региона Яндекса или region_key.

История и ряд показателей ограничены 31 датой за вызов. Для длинного периода делите запрос на части. null вместо позиции означает отсутствие позиции в отслеживаемой глубине выдачи. После нового съёма сначала дождитесь завершения через topvisor_audit_check_status.

Почему снимки выдачи пустые, хотя позиции есть?

Снимки доступны, только если их запись была включена при съёме. Включение do_snapshots через topvisor_project_update относится к будущим съёмам и требует подтверждения изменения. Затем получите новую цену: запись снимков влияет на стоимость.

topvisor_competitors_list показывает добавленных конкурентов, а topvisor_snapshots_competitors — домены из сохранённой выдачи. У второго инструмента метрика count_urls, а не средняя позиция или видимость.

Почему не показывается текущий баланс?

topvisor_bank_balance возвращает тариф и итоги операций по счёту. Текущий остаток счёта API не предоставляет, поэтому плагин его не рассчитывает. Для анализа списаний используйте topvisor_bank_log, для проверки текущего остатка — кабинет Топвизора.

Почему платный запуск отклонён или просит новую цену?

Даже при цене 0 требуется confirm_price=0 и разрешение платных запусков. Все условия описаны в статье «Проверки и расписание».

Цена аудита равна нулю, запуск отвечает ошибкой 5001. Что делать?

Проверьте страницы через topvisor_audit_pages_list. Они должны участвовать в нужной проверке. Добавьте недостающие через topvisor_audit_pages_create с флагом indexing или watcher, а существующие включите через topvisor_audit_pages_update.

Генерация карты сайта сама по себе не включает найденные страницы в индексацию и Радар. После подготовки страниц снова получите цену и подтвердите запуск.

Почему Радар не показывает изменений после первой проверки?

Радар сравнивает проверки, поэтому нужно минимум две. Прочитайте результаты через topvisor_audit_watcher: view=summary возвращает счётчики, view=changes — страницы с изменениями; with_diff запрашивает прежние и новые значения. Отсутствие изменений после двух проверок также может быть нормальным результатом.

Что делать, если неизвестно, применилось ли изменение или запуск?

При write_outcome_unknown запись могла выполниться. Перечитайте объект соответствующим инструментом чтения; не повторяйте действие до проверки.

При go_outcome_unknown платная проверка могла запуститься. Проверьте topvisor_audit_check_status и topvisor_bank_log.

При partial_failure часть шагов могла завершиться успешно. Изучите поля ответа и текущее состояние, затем исправляйте только недостающее. confirm_required означает ожидание подтверждения и предпросмотр, nothing_to_change — что запрошенные изменения уже не нужны.

Почему списания продолжаются после выключения платных проверок в плагине?

Флажок запрещает новые платные вызовы через плагин и включение расписания. Ранее сохранённый автозапуск выполняется в Топвизоре самостоятельно.

Прочитайте расписание через topvisor_schedule_get, затем выключите нужный вид через topvisor_schedule_delete после предпросмотра и подтверждения. Для выключения нужен доступ токена к этому инструменту; флажок платных проверок включать не требуется.

Можно ли вывести данные в теме или получать отчёты в Telegram?

Хелперов темы, хуков витрины и шаблонов для такого вывода в плагине нет. Отправки отчётов по расписанию на e-mail или в Telegram тоже нет. Плагин предоставляет данные MCP-клиенту; возможности дальнейшей обработки зависят от этого клиента.