Tavily — Search API для AI-агентов

Практический справочник по Tavily: как подключить AI-агента к вебу, выбрать метод API, проверить первый запрос и рассчитать расход кредитов.

Что такое Tavily

Tavily — API для поиска, извлечения и обхода веб-страниц, рассчитанный на приложения и AI-агентов. Через единый интерфейс приложение может искать актуальную информацию, получать содержимое страниц, строить карту сайта и запускать исследовательские задачи.

10 февраля 2026 года Tavily объявила о присоединении к Nebius. В официальном сообщении компания указала, что текущий способ использования Tavily и API для пользователей остаются прежними.

Какие методы доступны

Для Search и Extract доступны глубины basic и advanced. Research использует модели mini и pro; от выбранной модели зависят минимальная и максимальная стоимость задачи.

Подключение по REST API

Адрес и операции

Base URL: https://api.tavily.com

• POST /search — поиск;
• POST /extract — извлечение;
• POST /map — карта сайта;
• POST /crawl — обход;
• POST /research — создание исследовательской задачи;
• GET Research — получение состояния созданной задачи;
• GET /usage — данные об использовании кредитов.

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

Аутентификация

Все методы Tavily используют API-ключ. В REST API его передают как Bearer-токен в заголовке Authorization.

# Храните ключ в переменной окружения, а не в исходном коде
export TAVILY_API_KEY="tvly-..."
curl -X POST https://api.tavily.com/search -H "Content-Type: application/json" -H "Authorization: Bearer $TAVILY_API_KEY" -d '{"query":"latest AI agent frameworks"}'

Официальные библиотеки (SDK)

pip install tavily-python

npm install @tavily/core

SDK — библиотека, которая упрощает работу с API из конкретного языка. Официальный быстрый старт содержит примеры для Python, JavaScript и cURL: Quickstart.

Отслеживание проектов и сессий

К запросу можно добавить необязательный идентификатор проекта:

X-Project-ID: your-project-id

Он помогает группировать расходы и фильтровать запросы в журнале и панели использования. В SDK проект также можно указать при создании клиента или через переменную TAVILY_PROJECT.

Для многошаговых взаимодействий доступны заголовки:

• X-Session-Id — непрозрачный идентификатор связанной последовательности запросов;
• X-Human-Id — непрозрачный идентификатор конечного пользователя.

Tavily сообщает, что X-Human-Id хешируется перед обработкой или хранением. Не помещайте в эти заголовки имя, email и другие непосредственно идентифицирующие данные.

Как проверить первый запрос

1. Создайте ключ на платформе Tavily и сохраните его в TAVILY_API_KEY.
2. Выполните запрос из раздела «Аутентификация».
3. Убедитесь, что команда выводит ответ поиска и не завершается ошибкой авторизации или ограничением частоты.
4. Проверьте расход кредитов в панели Tavily или через операцию Usage.
5. Повторите запрос с типичными для вашего агента формулировками и оцените полезность найденных источников.

Если API возвращает 429 Too Many Requests, прочитайте заголовок retry-after. В нём указано число секунд до следующей попытки. Логика повторов должна учитывать это значение.

Сколько стоит каждый метод

Неудачное извлечение URL не тарифицируется. Для Map также не списываются кредиты за неудачный запрос.

Пример из документации: обход 10 страниц с базовой глубиной извлечения стоит 1 кредит за картирование и 2 кредита за извлечение, всего 3 кредита. С глубиной advanced тот же объём стоит 5 кредитов.

Тарифы

Режим pay-as-you-go позволяет оплачивать дополнительные кредиты после исчерпания включённого в план объёма. Бесплатный план предоставляет 1 000 кредитов в месяц без банковской карты.

Лимиты запросов

Ограничения зависят от среды ключа: Development или Production.

Опрос состояния уже созданной задачи Research подчиняется стандартному лимиту, а не ограничению на создание задач.

Полезные сценарии

Ежедневный дайджест

Задача: ежедневно получать новости по пяти темам.

Исходное условие: агент запускается один раз в день и отправляет по одному запросу Search на каждую тему.

Действие: используйте Search advanced для пяти запросов. Это 10 кредитов за запуск, или около 300 кредитов за 30 дней.

Наблюдаемый результат: агент получает ответ поиска по каждой теме, а расход отражается в панели Tavily или через операцию Usage.

Ограничение: расчёт предполагает один запуск в день. Если запросы дают много нерелевантных источников, добавьте фильтрацию перед передачей результатов агенту.

Обновление базы знаний с сайта документации

Задача: получить содержимое выбранных страниц сайта для последующей индексации.

Исходное условие: URL сайта известен, но сначала нужно определить набор страниц.

Действие: вызовите Map, получите список URL и передайте выбранные адреса в Extract. Если нужно автоматически пройти сайт с извлечением содержимого, используйте Crawl: он объединяет картирование и извлечение, поэтому отдельный Map для этого варианта не требуется.

Наблюдаемый результат: получен набор URL и содержимое страниц для дальнейшей индексации. Для 10 страниц с базовой глубиной примерная стоимость Crawl по формуле документации составляет 3 кредита.

Ограничение: стоимость растёт вместе с числом успешно обработанных страниц. Перед большим обходом ограничьте объём и проверьте первые результаты.

Исследовательский отчёт

Задача: собрать более глубокий материал с минимальным объёмом собственной оркестрации.

Исходное условие: точную стоимость заранее определить нельзя, но допустим диапазон расходов.

Действие: создайте задачу через POST /research, выберите модель mini или pro, затем используйте GET-операцию для проверки состояния.

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

Ограничение: mini расходует от 4 до 110 кредитов, pro — от 15 до 250 кредитов за задачу.

Как контролировать бесплатный лимит

При 1 000 кредитов в месяц полезно заранее считать верхнюю границу:

• 1 000 базовых поисков или 500 продвинутых поисков, если не используются другие методы;
• ежедневный дайджест из пяти продвинутых запросов — около 300 кредитов за 30 дней;
• четыре задачи Research pro по максимальной цене — до 1 000 кредитов;
• сочетание Search, Map, Crawl и Research нужно считать по каждому этапу отдельно.

Когда Tavily подходит, а когда нужен другой инструмент

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

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

Ограничения

• Research тарифицируется динамически в пределах опубликованного диапазона.
• Production-ключ требует платного плана или включённого pay-as-you-go.
• Crawl и создание задач Research имеют отдельные лимиты даже для Production-ключей.
• Тарифы и ограничения относятся к изменяемым условиям сервиса; проверяйте их перед расчётом бюджета.
• Документация не заменяет проверку качества на ваших языках, темах и типах запросов.

Официальные ссылки

• Сайт Tavily
• Документация
• Введение в API
• Быстрый старт
• Кредиты и цены
• Лимиты запросов
• API Playground
• Репозитории и SDK

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

Следующий шаг

Сравните Tavily с другим поисковым API по цене, лимитам и подходу к работе агента: Brave Search API — поисковый API для AI-агентов

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov