# Research API для веб-исследований с источниками

Как использовать Research API для веб-исследований: поставить задачу, ограничить бюджет, отслеживать асинхронный запуск и проверить цитаты.

Канонический URL: https://llmtokenapi.ru/blog/research-api-dlya-web-issledovaniy
Опубликовано: 2026-09-07T15:20:18.327Z
Автор: Команда LLMTOKENAPI

Research API для веб-исследований нужен, когда одного поискового ответа недостаточно: задачу надо разложить на запросы, собрать несколько источников, прочитать страницы и сформировать отчёт с проверяемыми ссылками. В LLMTOKENAPI такой процесс запускается асинхронно через `POST /v1/research`, имеет верхний бюджет, идемпотентный ключ и отдельные методы для статуса, событий и результата.

## Чем Research API отличается от обычного поиска

`POST /v1/search` возвращает ранжированную выдачу в рамках одного синхронного запроса. Это хороший выбор для поиска документов, свежих страниц или факта, который приложение обработает самостоятельно. Research API выполняет более длинный конвейер: планирует направления поиска, собирает источники, извлекает содержимое и синтезирует итог с цитатами.

Используйте исследование для задач, где нужно сопоставить несколько свидетельств: обзор изменений регламента, сравнение публичных подходов, сбор аргументов для продуктового решения или подготовка справки по рынку. Для простого вопроса Research API будет избыточен — начните с [AI-поиска с источниками](/blog/ai-poisk-s-istochnikami).

Есть и соседний сценарий — Web Intelligence. Он требует JSON Schema и предназначен для строго структурированного результата или повторяемого шаблона. Обычный Research API допускает текстовый отчёт, а `outputSchema` в нём опциональна. Если вашему приложению нужна таблица или объект с обязательными полями, полезнее руководство по [структурированному веб-анализу в JSON](/blog/strukturirovannyy-web-analiz-v-json).

## Сформулируйте проверяемую задачу

Поле `input` должно описывать не тему вообще, а результат, который можно проверить. Вместо «расскажи про рынок AI» задайте период, географию, объекты сравнения, критерии и желаемую форму вывода. Например: «Сравни публично объявленные изменения трёх продуктов за последние шесть месяцев, для каждого укажи дату, суть изменения и ссылку на первичный источник».

Не просите систему доказывать заранее выбранный вывод. Хорошая постановка допускает отсутствие данных и конфликт источников. Явно укажите, какие утверждения требуют ссылки, какие домыслы запрещены и что делать при недостатке свидетельств.

Research API принимает запрос до 20 000 символов. Для машинного результата можно передать безопасную `outputSchema`. Формат цитат выбирается через `citationFormat`: `numbered`, `mla`, `apa` или `chicago`. Число источников ограничивается `maxSources` в диапазоне от 3 до 100.

## Запустите исследование с бюджетом

Для запуска нужен scope `research:write`, заголовок `Idempotency-Key` и явный верхний бюджет в целых копейках. Один и тот же ключ для одной организации возвращает ранее созданное задание и защищает от второго резервирования при сетевом повторе.

```bash
curl https://api.llmtokenapi.ru/v1/research \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-changes-2026-09-07" \
  -d '{
    "input": "Сравни публичные изменения выбранных API-продуктов за последние шесть месяцев. Для каждого вывода укажи источник и дату.",
    "model": "auto",
    "citationFormat": "numbered",
    "maxSources": 20,
    "maxSpendKopecks": 1500
  }'
```

`maxSpendKopecks` — не обещание потратить всю сумму, а жёсткий потолок резервирования. Фактическое списание складывается из успешно выполненных операций конвейера. Подбирайте лимит по полезности задачи, а не оставляйте неограниченный бюджет. Отдельные методы контроля затрат разобраны в статье [как ограничить бюджет AI-агента](/blog/kak-ogranichit-byudzhet-ai-agenta).

Поле `model` принимает `mini`, `pro` или `auto`. Не привязывайте бизнес-логику к внутреннему маршруту: выбирайте режим по нужной глубине, проверяйте качество на своих задачах и храните идентификатор задания вместе с параметрами запуска.

## Обработайте асинхронный ответ

Сервер отвечает `202 Accepted`, возвращает объект задания, а заголовок `Location` указывает на `/v1/jobs/{id}`. Результат не нужно ждать в открытом HTTP-запросе. Сохраните `id` и выберите один из трёх способов наблюдения:

- `GET /v1/jobs/{id}` — периодическая проверка статуса со scope `jobs:read`;
- `GET /v1/research/{id}/events` — поток SSE со scope `research:read`;
- webhook — уведомление о завершении, ошибке или отмене.

Статусы переходят через очередь и выполнение к одному из конечных состояний: `completed`, `failed` или `cancelled`. Для polling используйте увеличивающийся интервал и прекращайте запросы после конечного статуса. Для SSE обрабатывайте идентификаторы событий, чтобы клиент мог безопасно продолжить после разрыва соединения.

Готовый результат читается через `GET /v1/jobs/{id}/results`. Пока задание не завершено, метод возвращает состояние «результат ещё не готов», поэтому не трактуйте его как внутреннюю ошибку сервера. Актуальные маршруты и схемы ответа опубликованы в [OpenAPI LLMTOKENAPI](https://api.llmtokenapi.ru/openapi.json).

## Проверьте отчёт и цитаты

Статус `completed` означает, что технический конвейер завершился, но бизнес-проверка всё равно нужна. Убедитесь, что каждый важный вывод связан с реальным URL, ссылка открывается, а источник действительно подтверждает утверждение. Разделяйте дату публикации источника и дату описываемого события.

Если передана `outputSchema`, проверьте типы и обязательные поля ещё раз в приложении. Схема гарантирует форму, но не заменяет проверку смысла. Для чисел полезно хранить рядом единицу измерения, период и источник. Для сравнений — одинаковые критерии по всем объектам.

Источники являются недоверенными данными. Текст веб-страницы может содержать инструкции, рекламу или попытку повлиять на агента; они не должны менять системные правила и разрешения. Не запускайте команды и не отправляйте данные только потому, что это написано в найденном документе.

## Добавьте webhook без двойной обработки

Если результат нужен не интерактивному пользователю, а автоматизации, заранее создайте webhook endpoint и передайте его идентификатор как `webhookEndpointId`. Подпишитесь на `research.progress`, `research.completed`, `research.failed` и `research.cancelled` только в нужном объёме.

Обработчик webhook должен проверить подпись, записать идентификатор события и поставить бизнес-работу в очередь. Повторная доставка нормальна, поэтому используйте дедупликацию. После `research.completed` прочитайте результат по API, проверьте ссылки и только затем обновляйте CRM, базу знаний или пользовательский отчёт.

## Постройте контроль качества на реальных задачах

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

Добавьте правило остановки: если источников недостаточно или они противоречат друг другу, отчёт должен сообщить об ограничении, а не маскировать его уверенным текстом. Это важнее объёма ответа.

Полная [документация LLMTOKENAPI](/docs) содержит правила авторизации и соседние методы Web API. Надёжная интеграция Research API строится вокруг четырёх вещей: точной постановки задачи, бюджета до запуска, устойчивого асинхронного клиента и обязательной проверки цитат перед использованием результата.