# 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 费用。

### 计费参考

- 计量方式：按响应单位计量。
- 参考请求估算：0.016 美元。
- 单位成本基准：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": "从搜索结果中过滤成人或不安全内容。仅限企业版；search_depth 为 fast 或 ultra-fast 时不支持。"
    },
    "include_favicon": {
      "type": "boolean",
      "default": false,
      "description": "为每条结果包含 favicon URL。"
    },
    "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 生成答案。include_answer 为 false 或未生成答案时为 null。"
    },
    "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": "搜索结果的 Favicon URL。"
          },
          "raw_content": {
            "type": [
              "string",
              "null"
            ],
            "description": "清洗并解析后的来源内容。除非请求 include_raw_content，否则为 null；没有可用的原始内容时同样为 null。"
          }
        }
      }
    },
    "response_time": {
      "type": "number",
      "format": "float",
      "description": "完成该请求所用的时间（秒）。"
    },
    "usage": {
      "type": "object",
      "properties": {
        "credits": {
          "type": "integer",
          "description": "此请求消耗的资源单位，不是美元或 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 — 需要有效的 Felo API 密钥。

### 402 — 由于未满足计费要求，请求无法继续。

### 403 — 该账户无权执行此操作。

### 429 — 已达到请求或支出限额。

### 502 — 服务无法完成该请求。

### 503 — API 或计费服务暂时不可用。

### 504 — 服务在处理请求时超时。

### default — 错误响应；上游透传响应可能采用提供方格式

**application/json**

Schema:

```json
{}
```