Seolity для ИИ — как подключить к своему ассистенту

Seolity можно связать с любым ИИ-ассистентом (ChatGPT, Claude, ваш собственный агент). Ассистент на платном тарифе умеет не только читать готовые отчёты, но и сам запускать анализ релевантности, а после правки страницы пересчитывать его на тех же конкурентах и показывать, что изменилось. Настройка занимает 3 шага.

Как это работает

Схема для одной страницы:

Вы даёте ассистенту пару «запрос → страница» и токен.
Ассистент считает смету, запускает анализ и ждёт результат (обычно несколько минут).
Читает отчёт: что убрать (переспам, текст не по теме), что добавить (недостающие слова), что поправить в Title.
Готовит правку текста. Публикуете её вы или ассистент, если у него есть доступ к сайту и ваше разрешение.
После правки ассистент запускает пересчёт на тех же конкурентах и получает «было/стало»: стало лучше, хуже или без изменений, какой переспам ушёл, какие слова добавились.

Пересчёт на тех же конкурентах нужен, чтобы отделить эффект вашей правки от движения выдачи. Новый анализ по свежей выдаче смешивает одно с другим.

Кластеризацию по-прежнему запускаете вы в кабинете, а ассистент читает её результат через API: карту страниц, позиции вашего сайта по фразам, конкурентов.

Шаг 1. Получите API-токен

Войдите в кабинет seolity.ru.
Откройте страницу https://seolity.ru/api/ (раздел «API»).
Скопируйте свой ключ. Это Bearer-токен, ассистент передаёт его в заголовке Authorization: Bearer <токен>. В адресе запроса (?token=) ключ не принимается.

API работает на платном тарифе. Токен видит только ваши прогоны и анализы.

На той же странице задайте дневной потолок списаний через API (по умолчанию он равен дневному лимиту вашего тарифа: Джун 5, Мидл 20, Сеньор 50 юнитов). Ассистент не сможет потратить больше, даже если ошибётся.

Шаг 2. Загрузите документ «Возможности Seolity» в свой ИИ

Скачайте или скопируйте документ «Возможности Seolity» (кнопка на этой странице) и добавьте его в знания своего ИИ:

ChatGPT: создайте проект или Custom GPT и добавьте документ в Knowledge, либо вставьте его текст в начало чата.
Claude: добавьте документ в Project knowledge, либо вставьте в начало разговора.
Свой агент: положите документ как системный контекст или справочник.

Документ объясняет ИИ, что умеет Seolity, какие эндпоинты вызывать и в каком порядке. Полное описание полей есть в справке https://seolity.ru/blog/api-documentaciya/

Шаг 3. Порядок работы ассистента

Ассистент должен идти строго по шагам, иначе он потратит лишнее или получит неверный вывод.

Смета: POST /api/run/estimate/ с парами «запрос → URL». В ответе charge.units (сколько юнитов уйдёт), blocking[] (что мешает запуску) и can_launch.
Запуск: POST /api/run/ с теми же полями плюс idempotency_key (любая своя строка, например «site-zapros-2026-10-08») и confirm_cost из сметы. Если цена разошлась со сметой, анализ не запустится (код 409), а повтор с тем же idempotency_key вернёт уже созданный прогон, а не создаст второй.
Ожидание: GET /api/run/<id>/pairs/ раз в 1-2 минуты, пока finished не станет true. Там же percent и eta_minutes.
Что убрать: GET /api/run/<id>/analysis/?ids=... - переспам, слова не по теме, предложения-кандидаты на удаление, объём текста.
Что добавить: GET /api/run/<id>/tz/?ids=... - ТЗ копирайтеру. Сначала чистка, потом добор.
Правка страницы.
Смета пересчёта: POST /api/run/<id>/recalc/ с dry_run=true.
Пересчёт: тот же запрос без dry_run, с idempotency_key и confirm_cost из сметы.
Ожидание нового прогона через /pairs/, затем GET /api/run/<новый id>/diff/ - итог «было/стало».
Журнал и остатки: GET /api/usage/.

Сколько это стоит

Цены те же, что в кабинете, и списываются тем же способом:

одна строка анализа = 1 юнит из пула тарифа;
сверх дневного лимита тарифа при включённом овердрафте строка стоит 5 юнитов;
когда пул закончился, списывается 1 поштучный кредит;
пересчёт дешевле: 1 юнит или кредит за 2 строки. Пересчёт не тратит дневной лимит тарифа и не уходит в овердрафт.

Списание происходит в момент старта строки. Смета показывает, откуда возьмутся юниты: from_pool, from_credits, overdraft_rows, и сколько осталось: pool_left, credits_left, cap_left.

Лимиты, которые защищают от зацикливания

до 100 строк в одном запуске;
до 500 строк в сутки через API на аккаунт;
до 100 строк в сутки на один сайт;
ту же пару (запрос, URL, поисковик, регион, глубина ТОПа) через API можно запустить не чаще раза в 24 часа. Повтор вернёт 409 и ссылку на готовый анализ в duplicates[].read: его нужно читать, а не запускать заново;
пересчёт той же пары - не чаще раза в час;
дневной потолок списаний, который вы задали на https://seolity.ru/api/

Сутки считаются по календарю и обнуляются в полночь.

Что означают ответы с ошибкой

402 no_funds - не хватает юнитов и кредитов. Пополнить: https://seolity.ru/wallet/
429 - дневной лимит исчерпан. Поле code говорит какой: spend_cap (ваш потолок, менять на https://seolity.ru/api/), daily_limit (500 строк в сутки), site_daily_limit (100 строк на сайт), tariff_daily_limit (дневной лимит тарифа, а овердрафт выключен), global_daily_limit (общий предохранитель сервиса). Заголовок Retry-After говорит, сколько ждать до сброса.
409 - запуск не создан: повтор пары (duplicates), confirm_cost не совпал со сметой, слишком много строк в одном запуске (run_limit), запускать нечего (empty), неизвестные пары в пересчёте (unknown_ids).
403 - у аккаунта нет активной подписки.

На 409 и 429 ассистент должен остановиться и прочитать готовое, а не повторять запрос.

Где смотреть расход

В кабинете на странице https://seolity.ru/api/ есть блок «Запуски через API»: потолок дня, сколько списано сегодня и таблица прогонов за 30 дней (тип, строк, списано, откуда: пул, кредиты или овердрафт, последние цифры ключа).

То же через API: GET /api/usage/?days=30.

Пример первого промпта

«Ты работаешь с Seolity по загруженному документу возможностей. Мой токен: ВАШ_ТОКЕН. Страница https://site.ru/uslugi/remont/ должна ранжироваться по запросу "ремонт квартир под ключ" в Яндексе, Москва. Посчитай смету анализа, покажи её мне и после моего "да" запусти. Потом дай список правок: сначала что убрать, потом что добавить. После того как я опубликую правку, сделай пересчёт и покажи "было/стало".»

Кластеризацию ядра запускаете вы в кабинете, ассистент может заранее посчитать к ней смету, а потом прочитать результат.

Документ «Возможности Seolity»

Это тот самый файл, который нужно загрузить в свой ИИ (пункт «Шаг 2»). Скачайте .md или скопируйте текст целиком и добавьте его в знание ассистента.

Скачать .md

# Возможности Seolity — контекст для ИИ-ассистента

Назначение: этот документ описывает, что умеет сервис Seolity (seolity.ru) и как ИИ-ассистенту с ним работать. Загрузите его в свой ИИ (ChatGPT, Claude, кастомный агент) как знание/контекст. После этого ИИ сможет запускать анализ релевантности, разбирать результаты и проверять эффект своих правок пересчётом.

## Как устроена работа: что ИИ запускает сам, а что — человек

Seolity — SaaS для SEO-анализа. Ключевой принцип взаимодействия с ИИ:

- Анализ релевантности (одиночный и пакетный) и пересчёт «было/стало» ИИ запускает сам по ключу платного тарифа: смета → запуск → чтение → правка → пересчёт на тех же конкурентах → сравнение. Списание — с пула анализов аккаунта по цене кабинета: анализ 1 юнит, пересчёт 1 юнит за 2 строки. Дневной потолок списаний через API хозяин аккаунта задаёт на https://seolity.ru/api/.
- Кластеризацию, анализ шаблона, кросс-анализ запускает человек в кабинете; ИИ читает результат по API.
- Без запуска нового прогона через API доступны: пересчёт готовой кластеризации с другими стоп-доменами (`POST /api/clustering/<id>/recluster/`) и фоновая сборка ТЗ по прогону (`POST /api/run/<id>/tz/build/`).

Важное правило для ИИ: если задача требует данных, которых ещё нет, — не отвечай «через API нельзя, значит не сделаем». Анализ релевантности запусти сам (сначала смета, `/api/run/estimate/`). Для остального: «Запустите такой-то прогон в кабинете Seolity и пришлите ссылку — я заберу результат через API и разберу». Получил 402 или 429 — остановись и скажи человеку, что кончилось (анализы или дневной потолок), не повторяй запрос.

## Авторизация

- Все данные ИИ берёт только через API `https://seolity.ru/api/...` с заголовком `Authorization: Bearer <ВАШ_ТОКЕН>`. Ключ в адресе запроса (`?token=`) не принимается (401): адреса запросов оседают в логах.
- Токен — это ваш API-ключ. Взять на странице https://seolity.ru/api/ (раздел «API», доступно на платном тарифе).
- Один токен видит только ваши прогоны.
- Поле `apiVersion` в ответах меняется при правке формата (сейчас `2026.10.08`). Увидел новую версию — перечитай блок `_instruction` в ответе: там порядок работы и расшифровка полей.
- ИИ не заходит на сервер по SSH и не парсит страницы кабинета — только API.

## Каталог возможностей

Для каждой возможности: что делает, как запустить в кабинете, что читать через API.

### 1. Кластеризация семантического ядра

Что делает: разбивает список запросов на кластеры (потенциальные страницы) и строит карту страниц — что создать, что доработать. Учитывает частотность (базовую/фразовую/точную), сезонность и годовой тренд, каннибализацию, дробление интента по Google, группировку запросов по страницам конкурента.

Как запустить: кабинет → Кластеризация → загрузить список запросов → выбрать настройки → подтвердить → запустить. URL результата: `seolity.ru/clustering/result/<id>/` (таблица кластеров) или `seolity.ru/clustering/pagemap/<id>/` (карта страниц).

Что читать через API:
- `GET /api/clustering/<id>/` — сырьё прогона: кластеры grp1-4 (`clusters`), частотности, домен-статистика; при режиме «Оба поисковика» — ещё `clusters_google` (кластеры по Google).
- `GET /api/clustering/<id>/report/` — карта страниц: `summary` + `hubs[]` по каждой потенциальной странице (`title`, `action` = new/expand/push/strengthen/defend, `totalExact`/`totalBase`, `landingUrl` и распределение позиций, `consensus` = сигнал «Google дробит хаб», `commercial[]`/`faq[]` — запросы, `seasonality` — профиль спроса/пик/годовой тренд).
- `GET /api/clustering/<id>/competitors/?domains=host1,host2` — группировка запросов по страницам конкурента и пробелы вашего сайта против него.
- `GET /api/clustering/<id>/?domain=site.ru&only=positions` — ПОЗИЦИИ вашего домена по каждой фразе без разбора выдачи: у каждой фразы `positions` = `found`, `position` (1 = первое место), `url`, `host`, `hosts[]` (каждый поддомен отдельно; www. не отличается от основного домена), `top_n`, `serp_status` (ok/empty/pending); вверху `positions_summary` (найдено / не найдено / по хостам). `?serp=0` — только без `serp_urls`. Для прогонов до 5000 фраз. Так решается задача «проверить N гипотез: есть ли наша страница в выдаче и на каком месте» — запустите кластеризацию этого списка с доменом сайта (ТОП до 50) и прочитайте позиции.
- `GET /api/clustering/<id>/status/` — лёгкий статус прогона: `status` (parsing/clustering/done/error), `percent`, `queries`, `eta_minutes` (оценка, не обещание), `rate_per_minute`, `retries_pending`. Результат читать после `status=done`.
- `GET|POST /api/clustering/estimate/` — смета прогона до запуска, без списания: `queries[]` (или `query_count`), `topN`, `engine`, `freqTypes`, `seasonality` → `cost.serp` / `cost.frequency` / `cost.seasonality` / `cost.total` и баланс после списания. Фразы проходят ту же чистку, что в кабинете. `GET /api/balance/` — бонусный баланс аккаунта.

Большие проекты (свыше ~5000 запросов, до 100 000) отдаются постранично — не пытайся забрать всё разом:
- `/api/clustering/<id>/?limit=&offset=&grp1=&min_exact=` — строки страницами (по умолчанию 1000, максимум 5000); в ответе `meta.rows_total`, `meta.next_offset` (null = конец).
- `/api/clustering/<id>/report/?limit=&offset=&action=&min_exact=` — хабы страницами (по умолчанию 200, сортировка по totalExact убыв.); `meta.hubs_total`, `meta.next_offset`; фильтр `action` = new|expand|push|strengthen|defend, а также `action=archived` — АРХИВНЫЕ хабы (владелец снял их с продвижения): у них есть `noiseScore` и `noiseReasons` («топ не пересекается с вашими конкурентами», «доминирует чужой бренд X», «нет своих позиций», «в топе агрегаторы») — готовое обоснование, почему запросы можно убрать из работ. В обычном ответе архивных нет, только счётчик `meta.archived`. `summary` всегда полный.
- Рабочий цикл ИИ для больших проектов: сначала `summary` → затем приоритетные хабы постранично/по фильтру (например `action=new&min_exact=50`) → углубляться в нужные хабы. Малые проекты без параметров отдаются целиком, как раньше.

Помощь в чистке ядра и карты страниц (ИИ готовит список — решение и кнопку жмёт человек в кабинете):
- `GET /api/clustering/<id>/junk/` — кандидаты в мусорные фразы с причинами. ИИ отдаёт человеку список фраз, тот вставляет его в «Чистка ядра» → «Вставить список от агента».
- `GET /api/clustering/<id>/archive-candidates/` — хабы «возможный шум» с причинами (`all=1` — все живые хабы). ИИ возвращает список названий хабов, человек отправляет их в архив в карте страниц.
- `GET /api/clustering/<id>/titles/` — заголовки страниц из выдачи (url → title, код ответа): по ним видно, кто в ТОПе — компания, агрегатор, статья или чужая ниша. Если сбор не запускали, поле `pending` покажет остаток; запускает человек кнопкой «Заголовки выдачи» в карте страниц.
- `GET /api/clustering/<id>/site-pages/` — инвентарь страниц вашего сайта из выгрузки краулера (Screaming Frog), которую человек загружает в кабинете: url, title, h1, объём, глубина, входящие ссылки, canonical. Отвечает на вопрос «есть ли у нас уже страница под хаб» — выдача на него не отвечает. `hubs=1` — хабы с кандидатами в целевую страницу.
- `POST /api/clustering/<id>/recluster/` — перекластеризация из сохранённой выдачи с новыми стоп-доменами и порогом: `{"stopDomains":[...], "threshold":4}`. Без нового съёма выдачи и без списаний.


### 2. Анализ текстовой релевантности страницы

Что делает: сравнивает одну вашу страницу с ТОПом по запросу — где недобор по словам, структуре, объёму; что дописать.

Как запустить: кабинет → Новый анализ → URL страницы + запрос. Много пар сразу — вкладка «Пакетный анализ» (строки «запрос;URL», до 2000 за прогон), там же режимы «по HTML-шаблону» и «анализ ниши» (только запросы). Анализ работает по Яндексу и Google.

Что читать через API:
- `GET /api/run/<run_id>/pairs/` — список пар «запрос → страница» прогона с их `public_id` (по нему открываются анализы; id прогона для анализа не подходит). Там же статус прогона: `run_status`, `finished`, `counts`, `percent`, `eta_minutes` (оценка) и `error` по каждой паре. Готовые пары — `ready=true`.
- `GET /api/analysis/<id>/status/` — статус одного анализа (queued / parsing / done / error). Пока анализ в работе, `GET /api/analysis/<id>/` отвечает 409, а не неполным отчётом.
- `GET /api/run/<run_id>/analysis/?ids=id1,id2` — полные анализы пар одним ответом. По умолчанию отдаются рабочие разделы (настройки, объёмы, сводка, рекомендации, переспам, подозрительные предложения, обязательные слова, Title); `fields=` задаёт свой набор, `full=1` — отчёт целиком.
- `GET /api/analysis/<id>/` — полный отчёт. В нём есть `settings` (как посчитан отчёт: учитывался ли noindex, глубина ТОП, нормализация) и `wordCounts` (total / indexable / noindexClosed / analyzed — сколько текста на странице, сколько вне noindex и сколько вошло в расчёт), `summary.volume` (сократить / оставить / добрать, с рекомендуемым объёмом) и сырые медианы ТОПа рядом с нормализованными (`medianRaw`, `topMedianRaw`).
- `GET /api/analysis-brief/<id>/` — сжатый отчёт.
- `GET /api/analysis/<id>/tz/` — готовое ТЗ копирайтеру по этой странице. Порядок работ всегда: сначала чистка (переспам, слова не по теме, подозрительные предложения — раздел «Что убрать со страницы»), потом добор объёма.
- ТЗ по всему прогону: `GET /api/run/<run_id>/tz/?ids=...` — выбранные пары сразу; без `ids` — постранично уже готовые. Массовая сборка: `POST /api/run/<run_id>/tz/build/` → прогресс `GET /api/run/<run_id>/tz/status/` → `GET /api/run/<run_id>/tz-zip/` (архив .md по парам).

История и замер «было/стало»:
- `GET /api/analysis/<id>/history/` — все анализы той же пары (запрос + страница + регион + ТОП + поисковик) по времени: Ширина, Глубина, Общая, объём, дельта к предыдущей точке и к первой. `kind` показывает, откуда дельта: `fresh_serp` — свежая выдача (в дельту входит движение ТОПа), `recalc_same_competitors` — пересчёт на тех же конкурентах (дельта — от правок страницы).
- `GET /api/run/<run_id>/diff/?base=<run_id>` — сравнение пар двух прогонов: `verdict` (better / same / worse), Ширина/Глубина/Общая, объём, % слов не по теме, переспам (`fixed` — ушёл, `new` — появился, `still` — остался), недостающие слова (`covered` — добавлены). Для пересчёта `base` подставляется сам.
- Чистый замер эффекта правки — пересчёт на тех же конкурентах: в кабинете кнопка «Пересчитать» на странице прогона (новый запрос выдачи не делается).

Запуск анализа через API (ключ платного тарифа):
- `GET|POST /api/run/estimate/` — смета без запуска: строки к запуску, повторы, лимиты, `charge` (сколько юнитов спишется: `units`, из пула/кредитов, овердрафт, потолок дня и остаток), `confirm_cost`, `blocking[]`, `can_launch`.
- `POST /api/run/` — запуск пакета; одиночный анализ — пакет из одной строки. Обязательны `idempotency_key` и `confirm_cost` из сметы (число юнитов; не совпало — 409, ничего не списано). Тело: `pairs` ([{query, url}] или строки «запрос;URL»), `engine` (yandex/google), `region`, `top` (10/20/30); режимы `mode=niche|html`.
- `POST /api/run/<run_id>/recalc/` — пересчёт готовых пар на тех же конкурентах: сначала `dry_run=true` (смета с `confirm_cost`), потом тот же запрос с `idempotency_key` и `confirm_cost`; затем `/pairs/` нового прогона и `/diff/`.
- `GET /api/usage/` — сколько списано через API сегодня, потолок и остаток, журнал прогонов.
- Цена: анализ — 1 юнит пула (сверх дневного лимита тарифа при включённом овердрафте — 5), пул кончился — 1 поштучный кредит; пересчёт — 1 юнит за 2 строки, дневной лимит не тратит.
- Лимиты ключа: 100 строк на прогон, 500 в сутки, 100 в сутки на один сайт; ту же пару с теми же настройками — не чаще раза в 24 ч (409 со ссылкой на готовый анализ), пересчёт той же пары — не чаще раза в час; дневной потолок списаний (по умолчанию = дневной лимит тарифа).
- Коды: 402 `no_funds` — кончились анализы (https://seolity.ru/wallet/); 429 + `Retry-After` — суточный лимит или потолок (`spend_cap`, `daily_limit`, `site_daily_limit`, `tariff_daily_limit`, `global_daily_limit`); 409 — повтор, смета не совпала, запускать нечего. На 402/409/429 не повторять тот же запрос.
- Подробно: https://seolity.ru/blog/api-documentaciya/

### 3. Анализ шаблона сайта

Что делает: сравнивает шаблон/структуру сайта с ТОПом по прогону — какие блоки, секции и слова есть у лидеров и чего не хватает вашему шаблону.

Как запустить: строится по пакетному прогону — на странице прогона в кабинете кнопка анализа шаблона.

Что читать через API: `GET /api/run/<id>/structure/`. HTML конкурентов хранится около 3 дней: если отчёт по прогону не открывали раньше, а прогон старше, ответ будет 409 — нужен свежий прогон. Для прогона-пересчёта отчёт не строится (свежая выдача не запрашивалась).

### 4. Кросс-анализ

Что делает: сравнивает несколько страниц одного сайта между собой — общий переспам, мусорные слова, сквозной текст. Показывает проблемы шаблона, а не отдельной страницы.

Как запустить: кабинет → Кросс-анализ (нужно минимум 2 готовых анализа страниц одного домена; новых анализов не запускает).

Что читать через API: `GET /api/cross-analysis/<id>/`.


## Как ИИ обычно это применяет

- Кластеризация → план уровня сайта: список страниц к созданию и доработке с приоритетом по точной частотности, каннибализация, кандидаты на разбиение, тайминг публикации по сезонности.
- Анализ релевантности → постраничное ТЗ: сначала что убрать, потом что дописать.
- Пересчёт на тех же конкурентах + `/diff/` или `/history/` → проверка, дала ли правка эффект.
- Анализ шаблона → шаблонные правки, общие для всего сайта.
- Кросс-анализ → чистка сквозного переспама и мусора.

Полная документация полей API: https://seolity.ru/blog/api-documentaciya/

Текст документа

Возможности Seolity — контекст для ИИ-ассистента

Назначение: этот документ описывает, что умеет сервис Seolity (seolity.ru) и как ИИ-ассистенту с ним работать. Загрузите его в свой ИИ (ChatGPT, Claude, кастомный агент) как знание/контекст. После этого ИИ сможет запускать анализ релевантности, разбирать результаты и проверять эффект своих правок пересчётом.

Как устроена работа: что ИИ запускает сам, а что — человек

Seolity — SaaS для SEO-анализа. Ключевой принцип взаимодействия с ИИ:

Анализ релевантности (одиночный и пакетный) и пересчёт «было/стало» ИИ запускает сам по ключу платного тарифа: смета → запуск → чтение → правка → пересчёт на тех же конкурентах → сравнение. Списание — с пула анализов аккаунта по цене кабинета: анализ 1 юнит, пересчёт 1 юнит за 2 строки. Дневной потолок списаний через API хозяин аккаунта задаёт на https://seolity.ru/api/.
Кластеризацию, анализ шаблона, кросс-анализ запускает человек в кабинете; ИИ читает результат по API.
Без запуска нового прогона через API доступны: пересчёт готовой кластеризации с другими стоп-доменами (POST /api/clustering/<id>/recluster/) и фоновая сборка ТЗ по прогону (POST /api/run/<id>/tz/build/).

Важное правило для ИИ: если задача требует данных, которых ещё нет, — не отвечай «через API нельзя, значит не сделаем». Анализ релевантности запусти сам (сначала смета, /api/run/estimate/). Для остального: «Запустите такой-то прогон в кабинете Seolity и пришлите ссылку — я заберу результат через API и разберу». Получил 402 или 429 — остановись и скажи человеку, что кончилось (анализы или дневной потолок), не повторяй запрос.

Авторизация

Все данные ИИ берёт только через API https://seolity.ru/api/... с заголовком Authorization: Bearer <ВАШ_ТОКЕН>. Ключ в адресе запроса (?token=) не принимается (401): адреса запросов оседают в логах.
Токен — это ваш API-ключ. Взять на странице https://seolity.ru/api/ (раздел «API», доступно на платном тарифе).
Один токен видит только ваши прогоны.
Поле apiVersion в ответах меняется при правке формата (сейчас 2026.10.08). Увидел новую версию — перечитай блок _instruction в ответе: там порядок работы и расшифровка полей.
ИИ не заходит на сервер по SSH и не парсит страницы кабинета — только API.

Каталог возможностей

Для каждой возможности: что делает, как запустить в кабинете, что читать через API.

1. Кластеризация семантического ядра

Что делает: разбивает список запросов на кластеры (потенциальные страницы) и строит карту страниц — что создать, что доработать. Учитывает частотность (базовую/фразовую/точную), сезонность и годовой тренд, каннибализацию, дробление интента по Google, группировку запросов по страницам конкурента.

Как запустить: кабинет → Кластеризация → загрузить список запросов → выбрать настройки → подтвердить → запустить. URL результата: seolity.ru/clustering/result/<id>/ (таблица кластеров) или seolity.ru/clustering/pagemap/<id>/ (карта страниц).

Что читать через API:

GET /api/clustering/<id>/ — сырьё прогона: кластеры grp1-4 (clusters), частотности, домен-статистика; при режиме «Оба поисковика» — ещё clusters_google (кластеры по Google).
GET /api/clustering/<id>/report/ — карта страниц: summary + hubs[] по каждой потенциальной странице (title, action = new/expand/push/strengthen/defend, totalExact/totalBase, landingUrl и распределение позиций, consensus = сигнал «Google дробит хаб», commercial[]/faq[] — запросы, seasonality — профиль спроса/пик/годовой тренд).
GET /api/clustering/<id>/competitors/?domains=host1,host2 — группировка запросов по страницам конкурента и пробелы вашего сайта против него.
GET /api/clustering/<id>/?domain=site.ru&only=positions — ПОЗИЦИИ вашего домена по каждой фразе без разбора выдачи: у каждой фразы positions = found, position (1 = первое место), url, host, hosts[] (каждый поддомен отдельно; www. не отличается от основного домена), top_n, serp_status (ok/empty/pending); вверху positions_summary (найдено / не найдено / по хостам). ?serp=0 — только без serp_urls. Для прогонов до 5000 фраз. Так решается задача «проверить N гипотез: есть ли наша страница в выдаче и на каком месте» — запустите кластеризацию этого списка с доменом сайта (ТОП до 50) и прочитайте позиции.
GET /api/clustering/<id>/status/ — лёгкий статус прогона: status (parsing/clustering/done/error), percent, queries, eta_minutes (оценка, не обещание), rate_per_minute, retries_pending. Результат читать после status=done.
GET|POST /api/clustering/estimate/ — смета прогона до запуска, без списания: queries[] (или query_count), topN, engine, freqTypes, seasonality → cost.serp / cost.frequency / cost.seasonality / cost.total и баланс после списания. Фразы проходят ту же чистку, что в кабинете. GET /api/balance/ — бонусный баланс аккаунта.

Большие проекты (свыше ~5000 запросов, до 100 000) отдаются постранично — не пытайся забрать всё разом:

/api/clustering/<id>/?limit=&offset=&grp1=&min_exact= — строки страницами (по умолчанию 1000, максимум 5000); в ответе meta.rows_total, meta.next_offset (null = конец).
/api/clustering/<id>/report/?limit=&offset=&action=&min_exact= — хабы страницами (по умолчанию 200, сортировка по totalExact убыв.); meta.hubs_total, meta.next_offset; фильтр action = new|expand|push|strengthen|defend, а также action=archived — АРХИВНЫЕ хабы (владелец снял их с продвижения): у них есть noiseScore и noiseReasons («топ не пересекается с вашими конкурентами», «доминирует чужой бренд X», «нет своих позиций», «в топе агрегаторы») — готовое обоснование, почему запросы можно убрать из работ. В обычном ответе архивных нет, только счётчик meta.archived. summary всегда полный.
Рабочий цикл ИИ для больших проектов: сначала summary → затем приоритетные хабы постранично/по фильтру (например action=new&min_exact=50) → углубляться в нужные хабы. Малые проекты без параметров отдаются целиком, как раньше.

Помощь в чистке ядра и карты страниц (ИИ готовит список — решение и кнопку жмёт человек в кабинете):

GET /api/clustering/<id>/junk/ — кандидаты в мусорные фразы с причинами. ИИ отдаёт человеку список фраз, тот вставляет его в «Чистка ядра» → «Вставить список от агента».
GET /api/clustering/<id>/archive-candidates/ — хабы «возможный шум» с причинами (all=1 — все живые хабы). ИИ возвращает список названий хабов, человек отправляет их в архив в карте страниц.
GET /api/clustering/<id>/titles/ — заголовки страниц из выдачи (url → title, код ответа): по ним видно, кто в ТОПе — компания, агрегатор, статья или чужая ниша. Если сбор не запускали, поле pending покажет остаток; запускает человек кнопкой «Заголовки выдачи» в карте страниц.
GET /api/clustering/<id>/site-pages/ — инвентарь страниц вашего сайта из выгрузки краулера (Screaming Frog), которую человек загружает в кабинете: url, title, h1, объём, глубина, входящие ссылки, canonical. Отвечает на вопрос «есть ли у нас уже страница под хаб» — выдача на него не отвечает. hubs=1 — хабы с кандидатами в целевую страницу.
POST /api/clustering/<id>/recluster/ — перекластеризация из сохранённой выдачи с новыми стоп-доменами и порогом: {"stopDomains":[...], "threshold":4}. Без нового съёма выдачи и без списаний.

2. Анализ текстовой релевантности страницы

Что делает: сравнивает одну вашу страницу с ТОПом по запросу — где недобор по словам, структуре, объёму; что дописать.

Как запустить: кабинет → Новый анализ → URL страницы + запрос. Много пар сразу — вкладка «Пакетный анализ» (строки «запрос;URL», до 2000 за прогон), там же режимы «по HTML-шаблону» и «анализ ниши» (только запросы). Анализ работает по Яндексу и Google.

Что читать через API:

GET /api/run/<run_id>/pairs/ — список пар «запрос → страница» прогона с их public_id (по нему открываются анализы; id прогона для анализа не подходит). Там же статус прогона: run_status, finished, counts, percent, eta_minutes (оценка) и error по каждой паре. Готовые пары — ready=true.
GET /api/analysis/<id>/status/ — статус одного анализа (queued / parsing / done / error). Пока анализ в работе, GET /api/analysis/<id>/ отвечает 409, а не неполным отчётом.
GET /api/run/<run_id>/analysis/?ids=id1,id2 — полные анализы пар одним ответом. По умолчанию отдаются рабочие разделы (настройки, объёмы, сводка, рекомендации, переспам, подозрительные предложения, обязательные слова, Title); fields= задаёт свой набор, full=1 — отчёт целиком.
GET /api/analysis/<id>/ — полный отчёт. В нём есть settings (как посчитан отчёт: учитывался ли noindex, глубина ТОП, нормализация) и wordCounts (total / indexable / noindexClosed / analyzed — сколько текста на странице, сколько вне noindex и сколько вошло в расчёт), summary.volume (сократить / оставить / добрать, с рекомендуемым объёмом) и сырые медианы ТОПа рядом с нормализованными (medianRaw, topMedianRaw).
GET /api/analysis-brief/<id>/ — сжатый отчёт.
GET /api/analysis/<id>/tz/ — готовое ТЗ копирайтеру по этой странице. Порядок работ всегда: сначала чистка (переспам, слова не по теме, подозрительные предложения — раздел «Что убрать со страницы»), потом добор объёма.
ТЗ по всему прогону: GET /api/run/<run_id>/tz/?ids=... — выбранные пары сразу; без ids — постранично уже готовые. Массовая сборка: POST /api/run/<run_id>/tz/build/ → прогресс GET /api/run/<run_id>/tz/status/ → GET /api/run/<run_id>/tz-zip/ (архив .md по парам).

История и замер «было/стало»:

GET /api/analysis/<id>/history/ — все анализы той же пары (запрос + страница + регион + ТОП + поисковик) по времени: Ширина, Глубина, Общая, объём, дельта к предыдущей точке и к первой. kind показывает, откуда дельта: fresh_serp — свежая выдача (в дельту входит движение ТОПа), recalc_same_competitors — пересчёт на тех же конкурентах (дельта — от правок страницы).
GET /api/run/<run_id>/diff/?base=<run_id> — сравнение пар двух прогонов: verdict (better / same / worse), Ширина/Глубина/Общая, объём, % слов не по теме, переспам (fixed — ушёл, new — появился, still — остался), недостающие слова (covered — добавлены). Для пересчёта base подставляется сам.
Чистый замер эффекта правки — пересчёт на тех же конкурентах: в кабинете кнопка «Пересчитать» на странице прогона (новый запрос выдачи не делается).

Запуск анализа через API (ключ платного тарифа):

GET|POST /api/run/estimate/ — смета без запуска: строки к запуску, повторы, лимиты, charge (сколько юнитов спишется: units, из пула/кредитов, овердрафт, потолок дня и остаток), confirm_cost, blocking[], can_launch.
POST /api/run/ — запуск пакета; одиночный анализ — пакет из одной строки. Обязательны idempotency_key и confirm_cost из сметы (число юнитов; не совпало — 409, ничего не списано). Тело: pairs ([{query, url}] или строки «запрос;URL»), engine (yandex/google), region, top (10/20/30); режимы mode=niche|html.
POST /api/run/<run_id>/recalc/ — пересчёт готовых пар на тех же конкурентах: сначала dry_run=true (смета с confirm_cost), потом тот же запрос с idempotency_key и confirm_cost; затем /pairs/ нового прогона и /diff/.
GET /api/usage/ — сколько списано через API сегодня, потолок и остаток, журнал прогонов.
Цена: анализ — 1 юнит пула (сверх дневного лимита тарифа при включённом овердрафте — 5), пул кончился — 1 поштучный кредит; пересчёт — 1 юнит за 2 строки, дневной лимит не тратит.
Лимиты ключа: 100 строк на прогон, 500 в сутки, 100 в сутки на один сайт; ту же пару с теми же настройками — не чаще раза в 24 ч (409 со ссылкой на готовый анализ), пересчёт той же пары — не чаще раза в час; дневной потолок списаний (по умолчанию = дневной лимит тарифа).
Коды: 402 no_funds — кончились анализы (https://seolity.ru/wallet/); 429 + Retry-After — суточный лимит или потолок (spend_cap, daily_limit, site_daily_limit, tariff_daily_limit, global_daily_limit); 409 — повтор, смета не совпала, запускать нечего. На 402/409/429 не повторять тот же запрос.
Подробно: https://seolity.ru/blog/api-documentaciya/

3. Анализ шаблона сайта

Что делает: сравнивает шаблон/структуру сайта с ТОПом по прогону — какие блоки, секции и слова есть у лидеров и чего не хватает вашему шаблону.

Как запустить: строится по пакетному прогону — на странице прогона в кабинете кнопка анализа шаблона.

Что читать через API: GET /api/run/<id>/structure/. HTML конкурентов хранится около 3 дней: если отчёт по прогону не открывали раньше, а прогон старше, ответ будет 409 — нужен свежий прогон. Для прогона-пересчёта отчёт не строится (свежая выдача не запрашивалась).

4. Кросс-анализ

Что делает: сравнивает несколько страниц одного сайта между собой — общий переспам, мусорные слова, сквозной текст. Показывает проблемы шаблона, а не отдельной страницы.

Как запустить: кабинет → Кросс-анализ (нужно минимум 2 готовых анализа страниц одного домена; новых анализов не запускает).

Что читать через API: GET /api/cross-analysis/<id>/.

Как ИИ обычно это применяет

Кластеризация → план уровня сайта: список страниц к созданию и доработке с приоритетом по точной частотности, каннибализация, кандидаты на разбиение, тайминг публикации по сезонности.
Анализ релевантности → постраничное ТЗ: сначала что убрать, потом что дописать.
Пересчёт на тех же конкурентах + /diff/ или /history/ → проверка, дала ли правка эффект.
Анализ шаблона → шаблонные правки, общие для всего сайта.
Кросс-анализ → чистка сквозного переспама и мусора.

Полная документация полей API: https://seolity.ru/blog/api-documentaciya/