# 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 USD。
- ユニットコスト基準：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 を含めます。"
    },
    "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": "検索結果のファビコン 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
{}
```