# 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
{}
```