# Tavily Search

**API:** Data API

**Endpoint:** `POST /v1/beta/tavily/search`

**Tags:** Web Search

Ищет в интернете и возвращает ранжированные результаты с заголовками, URL и фрагментами содержимого. query обязателен. Используйте max_results для управления числом результатов и search_depth для выбора режима поиска. Дополнительный answer, images и исходное содержимое возвращаются только по запросу. Установите include_usage, чтобы получать сведения об использовании ресурсов; usage.credits — это не списание Felo.

### Справочная информация о ценах

- Тарификация: тарифицируемые единицы ответа.
- Справочная оценка запроса: USD 0.016.
- Базовая стоимость единицы: USD 0.008.
- Единица ресурса: `tavily_credit`.
- Справочный множитель для клиента: 1.0. Не применяйте его повторно к уже рассчитанной сумме клиента.
- Базовые стоимости не определяют итоговую цену для клиента, в том числе когда они равны нулю.

Только справочные метаданные, а не котировка для аккаунта, гарантированная цена или лимит расходов. Кредиты ресурсов — не кредиты Felo. Итоговые списания определяются записями биллинга Felo.

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Request body

Required: **yes**

### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Поисковый запрос для выполнения с помощью Tavily.",
      "example": "Who is Leo Messi?"
    },
    "search_depth": {
      "type": "string",
      "enum": [
        "advanced",
        "basic",
        "fast",
        "ultra-fast"
      ],
      "default": "basic",
      "description": "Управляет компромиссом между задержкой и релевантностью. advanced даёт максимальную релевантность при более высокой задержке и стоимости; basic — сбалансированный вариант; fast и ultra-fast оптимизированы для меньшей задержки."
    },
    "chunks_per_source": {
      "type": "integer",
      "default": 3,
      "description": "Максимальное количество релевантных чанков, возвращаемых на источник.",
      "minimum": 1,
      "maximum": 3
    },
    "max_results": {
      "type": "integer",
      "default": 5,
      "description": "Максимальное количество результатов поиска для возврата.",
      "minimum": 0,
      "maximum": 20
    },
    "topic": {
      "type": "string",
      "enum": [
        "general",
        "news",
        "finance"
      ],
      "default": "general",
      "description": "Категория поиска."
    },
    "time_range": {
      "type": "string",
      "enum": [
        "day",
        "week",
        "month",
        "year",
        "d",
        "w",
        "m",
        "y"
      ],
      "description": "Временной диапазон для фильтрации результатов по дате публикации."
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Возвращать результаты после указанной начальной даты.",
      "example": "2025-02-09"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Возвращать результаты до указанной конечной даты.",
      "example": "2025-12-29"
    },
    "include_answer": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "basic",
            "advanced"
          ]
        }
      ],
      "default": false,
      "description": "Включать ответ, сгенерированный LLM. true использует режим ответа по умолчанию; basic или advanced выбирает режим генерации ответа."
    },
    "include_raw_content": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "markdown",
            "text"
          ]
        }
      ],
      "default": false,
      "description": "Включать очищенное и разобранное содержимое для каждого результата поиска. true или markdown возвращает markdown; text возвращает обычный текст и может увеличить задержку."
    },
    "include_images": {
      "type": "boolean",
      "default": false,
      "description": "Выполнить поиск изображений и включить результаты."
    },
    "include_image_descriptions": {
      "type": "boolean",
      "default": false,
      "description": "Добавлять описательный текст для каждого изображения, когда include_images имеет значение true."
    },
    "safe_search": {
      "type": "boolean",
      "default": false,
      "description": "Отфильтровывать контент для взрослых или небезопасный контент из результатов поиска. Только для Enterprise; не поддерживается, когда search_depth имеет значение fast или ultra-fast."
    },
    "include_favicon": {
      "type": "boolean",
      "default": false,
      "description": "Включать URL favicon для каждого результата."
    },
    "include_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Список доменов, которые нужно явно включить в результаты поиска.",
      "maxItems": 300
    },
    "exclude_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Список доменов, которые нужно явно исключить из результатов поиска.",
      "maxItems": 150
    },
    "country": {
      "type": "string",
      "description": "Повышать релевантность результатов поиска из определённой страны. Доступно только когда topic имеет значение general.",
      "enum": [
        "afghanistan",
        "albania",
        "algeria",
        "andorra",
        "angola",
        "argentina",
        "armenia",
        "australia",
        "austria",
        "azerbaijan",
        "bahamas",
        "bahrain",
        "bangladesh",
        "barbados",
        "belarus",
        "belgium",
        "belize",
        "benin",
        "bhutan",
        "bolivia",
        "bosnia and herzegovina",
        "botswana",
        "brazil",
        "brunei",
        "bulgaria",
        "burkina faso",
        "burundi",
        "cambodia",
        "cameroon",
        "canada",
        "cape verde",
        "central african republic",
        "chad",
        "chile",
        "china",
        "colombia",
        "comoros",
        "congo",
        "costa rica",
        "croatia",
        "cuba",
        "cyprus",
        "czech republic",
        "denmark",
        "djibouti",
        "dominican republic",
        "ecuador",
        "egypt",
        "el salvador",
        "equatorial guinea",
        "eritrea",
        "estonia",
        "ethiopia",
        "fiji",
        "finland",
        "france",
        "gabon",
        "gambia",
        "georgia",
        "germany",
        "ghana",
        "greece",
        "guatemala",
        "guinea",
        "haiti",
        "honduras",
        "hungary",
        "iceland",
        "india",
        "indonesia",
        "iran",
        "iraq",
        "ireland",
        "israel",
        "italy",
        "jamaica",
        "japan",
        "jordan",
        "kazakhstan",
        "kenya",
        "kuwait",
        "kyrgyzstan",
        "latvia",
        "lebanon",
        "lesotho",
        "liberia",
        "libya",
        "liechtenstein",
        "lithuania",
        "luxembourg",
        "madagascar",
        "malawi",
        "malaysia",
        "maldives",
        "mali",
        "malta",
        "mauritania",
        "mauritius",
        "mexico",
        "moldova",
        "monaco",
        "mongolia",
        "montenegro",
        "morocco",
        "mozambique",
        "myanmar",
        "namibia",
        "nepal",
        "netherlands",
        "new zealand",
        "nicaragua",
        "niger",
        "nigeria",
        "north korea",
        "north macedonia",
        "norway",
        "oman",
        "pakistan",
        "panama",
        "papua new guinea",
        "paraguay",
        "peru",
        "philippines",
        "poland",
        "portugal",
        "qatar",
        "romania",
        "russia",
        "rwanda",
        "saudi arabia",
        "senegal",
        "serbia",
        "singapore",
        "slovakia",
        "slovenia",
        "somalia",
        "south africa",
        "south korea",
        "south sudan",
        "spain",
        "sri lanka",
        "sudan",
        "sweden",
        "switzerland",
        "syria",
        "taiwan",
        "tajikistan",
        "tanzania",
        "thailand",
        "togo",
        "trinidad and tobago",
        "tunisia",
        "turkey",
        "turkmenistan",
        "uganda",
        "ukraine",
        "united arab emirates",
        "united kingdom",
        "united states",
        "uruguay",
        "uzbekistan",
        "venezuela",
        "vietnam",
        "yemen",
        "zambia",
        "zimbabwe"
      ]
    },
    "auto_parameters": {
      "type": "boolean",
      "default": false,
      "description": "Автоматически настраивать параметры поиска на основе содержимого запроса."
    },
    "include_usage": {
      "type": "boolean",
      "default": false,
      "description": "Включать сведения об использовании ресурсов в ответ. Это не информация о биллинге Felo."
    }
  },
  "required": [
    "query"
  ]
}
```

Example:

```json
{
  "query": "Python official documentation",
  "search_depth": "basic",
  "max_results": 2,
  "include_usage": true
}
```

## Responses

### 200 — Результаты поиска успешно возвращены.

Headers:
- `X-Request-Id` (string) — Идентификатор запроса, который нужно указать при обращении в поддержку Felo.

**application/json**

Schema: object

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Поисковый запрос, который был выполнен."
    },
    "answer": {
      "type": [
        "string",
        "null"
      ],
      "description": "Короткий ответ, сгенерированный LLM. Равен null, если include_answer имеет значение false или ответ не сгенерирован."
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL изображения."
          },
          "description": {
            "type": "string",
            "description": "Описание изображения."
          }
        }
      }
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Заголовок результата поиска."
          },
          "url": {
            "type": "string",
            "description": "URL результата поиска."
          },
          "content": {
            "type": "string",
            "description": "Фрагмент содержимого результата поиска."
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Оценка релевантности результата поиска."
          },
          "favicon": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL favicon результата поиска."
          },
          "raw_content": {
            "type": [
              "string",
              "null"
            ],
            "description": "Очищенное и разобранное содержимое источника. Null, если include_raw_content не запрошен или необработанное содержимое недоступно."
          }
        }
      }
    },
    "response_time": {
      "type": "number",
      "format": "float",
      "description": "Время выполнения запроса в секундах."
    },
    "usage": {
      "type": "object",
      "properties": {
        "credits": {
          "type": "integer",
          "description": "Единицы ресурсов, израсходованные этим запросом; не USD и не кредиты Felo."
        }
      }
    },
    "request_id": {
      "type": "string",
      "description": "Уникальный идентификатор запроса."
    }
  }
}
```

Example:

```json
{
  "query": "Python official documentation",
  "answer": null,
  "images": [],
  "results": [
    {
      "title": "Python Documentation",
      "url": "https://docs.python.org/3/",
      "content": "Documentation for the Python programming language.",
      "score": 0.98,
      "raw_content": null
    }
  ],
  "response_time": 1.2,
  "usage": {
    "credits": 1
  },
  "request_id": "example-search-request"
}
```

### 400 — Запрос не удалось обработать. Проверьте параметры запроса.

### 401 — Требуется действительный API-ключ Felo.

### 402 — Запрос не может быть выполнен: не выполнено требование биллинга.

### 403 — Аккаунту не разрешено выполнять эту операцию.

### 429 — Достигнут лимит запросов или расходов.

### 502 — Сервис не смог выполнить запрос.

### 503 — API или сервис биллинга временно недоступны.

### 504 — Истекло время ожидания обработки запроса.

### default — Ответ с ошибкой; сквозные ответы upstream могут использовать форматы провайдера

**application/json**

Schema:

```json
{}
```