tavily

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tavily

Purpose

用途

Provide a curl-based interface to Tavily’s REST API for web search, extraction, mapping, crawling, and optional research. Return structured results suitable for LLM workflows and multi-step investigations.

提供基于curl的Tavily REST API接口，用于网页搜索、提取、映射、爬取及可选的研究工作。返回适用于LLM工作流和多步骤调查的结构化结果。

When to Use

使用场景

Use when a task needs live web information, site extraction, mapping, or crawling.
Use when web searches are needed and no built-in tool is available, or when Tavily’s LLM-friendly output (summaries, chunks, sources, citations) is beneficial.
Use when a task requires structured search results, extraction, or site discovery from Tavily.

当任务需要实时网页信息、站点内容提取、映射或爬取时使用。
当需要进行网页搜索且没有内置工具可用，或者Tavily的LLM友好输出（摘要、内容块、来源、引用）更具优势时使用。
当任务需要从Tavily获取结构化搜索结果、内容提取或站点发现功能时使用。

Required Environment

所需环境

Require
```
TAVILY_API_KEY
```
in the environment.
If
```
TAVILY_API_KEY
```
is missing, prompt the user to provide the API key before proceeding.

环境中需配置
```
TAVILY_API_KEY
```
。
如果缺少
```
TAVILY_API_KEY
```
，请提示用户提供该API密钥后再继续操作。

Base URL and Auth

基础URL与认证

Base URL:
```
https://api.tavily.com
```
Authentication:
```
Authorization: Bearer $TAVILY_API_KEY
```
Content type:
```
Content-Type: application/json
```
Optional project tracking: add
```
X-Project-ID: <project-id>
```
if project attribution is needed.

基础URL:
```
https://api.tavily.com
```
认证方式:
```
Authorization: Bearer $TAVILY_API_KEY
```
内容类型:
```
Content-Type: application/json
```
可选项目追踪: 如果需要项目归因，可添加
```
X-Project-ID: <project-id>
```
。

Tool Mapping (Tavily REST)

工具映射（Tavily REST）

1) search → POST /search

Use for web search with optional answer and content extraction.

Recommended minimal request:

bash

curl -sS -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "query": "<query>",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false,
    "include_images": false
  }'

Key parameters (all optional unless noted):

```
query
```
(required): search text
```
search_depth
```
:
```
basic
```
|
```
advanced
```
|
```
fast
```
|
```
ultra-fast
```
```
chunks_per_source
```
: 1–3 (advanced only)
```
max_results
```
: 0–20
```
topic
```
:
```
general
```
|
```
news
```
|
```
finance
```
```
time_range
```
:
```
day|week|month|year|d|w|m|y
```
```
start_date
```
,
```
end_date
```
:
```
YYYY-MM-DD
```
```
include_answer
```
:
```
false
```
|
```
true
```
|
```
basic
```
|
```
advanced
```

include_raw_content

false

true

markdown

text

```
include_images
```
: boolean
```
include_image_descriptions
```
: boolean
```
include_favicon
```
: boolean
```
include_domains
```
,
```
exclude_domains
```
: string arrays
```
country
```
: country name (general topic only)
```
auto_parameters
```
: boolean
```
include_usage
```
: boolean

Expected response fields:

answer

(if requested),

results[]

with

title

url

content

score

raw_content

(optional),

favicon

(optional)

```
response_time
```
,
```
usage
```
,
```
request_id
```

用于网页搜索，可选择开启答案和内容提取功能。

推荐的最小请求示例:

bash

curl -sS -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "query": "<query>",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false,
    "include_images": false
  }'

关键参数（除非标注，否则均为可选）:

```
query
```
（必填）: 搜索文本
```
search_depth
```
:
```
basic
```
|
```
advanced
```
|
```
fast
```
|
```
ultra-fast
```
```
chunks_per_source
```
: 1–3（仅高级模式可用）
```
max_results
```
: 0–20
```
topic
```
:
```
general
```
|
```
news
```
|
```
finance
```
```
time_range
```
:
```
day|week|month|year|d|w|m|y
```
```
start_date
```
,
```
end_date
```
:
```
YYYY-MM-DD
```
```
include_answer
```
:
```
false
```
|
```
true
```
|
```
basic
```
|
```
advanced
```

include_raw_content

false

true

markdown

text

```
include_images
```
: 布尔值
```
include_image_descriptions
```
: 布尔值
```
include_favicon
```
: 布尔值
```
include_domains
```
,
```
exclude_domains
```
: 字符串数组
```
country
```
: 国家名称（仅通用主题可用）
```
auto_parameters
```
: 布尔值
```
include_usage
```
: 布尔值

预期响应字段:

```
answer
```
（若请求）、
```
results[]
```
包含
```
title
```
、
```
url
```
、
```
content
```
、
```
score
```
、
```
raw_content
```
（可选）、
```
favicon
```
（可选）
```
response_time
```
、
```
usage
```
、
```
request_id
```

2) extract → POST /extract

Use for extracting content from specific URLs.

bash

curl -sS -X POST "https://api.tavily.com/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "urls": ["https://example.com/article"],
    "query": "<optional intent for reranking>",
    "chunks_per_source": 3,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false,
    "include_favicon": false
  }'

Key parameters:

```
urls
```
(required): array of URLs
```
query
```
: rerank chunks by intent
```
chunks_per_source
```
: 1–5 (only when
```
query
```
provided)
```
extract_depth
```
:
```
basic
```
|
```
advanced
```
```
format
```
:
```
markdown
```
|
```
text
```
```
timeout
```
: 1–60 seconds
```
include_usage
```
: boolean

Expected response fields:

```
results[]
```
with
```
url
```
,
```
raw_content
```
,
```
images
```
,
```
favicon
```

failed_results[]

response_time

usage

request_id

用于从特定URL提取内容。

bash

curl -sS -X POST "https://api.tavily.com/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "urls": ["https://example.com/article"],
    "query": "<optional intent for reranking>",
    "chunks_per_source": 3,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false,
    "include_favicon": false
  }'

关键参数:

```
urls
```
（必填）: URL数组
```
query
```
: 根据意图对内容块重新排序
```
chunks_per_source
```
: 1–5（仅当提供
```
query
```
时可用）
```
extract_depth
```
:
```
basic
```
|
```
advanced
```
```
format
```
:
```
markdown
```
|
```
text
```
```
timeout
```
: 1–60秒
```
include_usage
```
: 布尔值

预期响应字段:

```
results[]
```
包含
```
url
```
、
```
raw_content
```
、
```
images
```
、
```
favicon
```

failed_results[]

、

response_time

、

usage

、

request_id

3) map → POST /map

Use for generating a site map (URL discovery only).

bash

curl -sS -X POST "https://api.tavily.com/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "allow_external": true
  }'

Key parameters:

```
url
```
(required)
```
instructions
```
: natural language guidance (raises cost)
```
max_depth
```
: 1–5
```
max_breadth
```
: 1+
```
limit
```
: 1+

select_paths

select_domains

exclude_paths

exclude_domains

: arrays of regex strings

```
allow_external
```
: boolean
```
timeout
```
: 10–150 seconds
```
include_usage
```
: boolean

Expected response fields:

base_url

results[]

(list of URLs),

response_time

usage

request_id

用于生成站点地图（仅URL发现）。

bash

curl -sS -X POST "https://api.tavily.com/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "allow_external": true
  }'

关键参数:

```
url
```
（必填）
```
instructions
```
: 自然语言指导（会增加成本）
```
max_depth
```
: 1–5
```
max_breadth
```
: 1+
```
limit
```
: 1+

select_paths

select_domains

exclude_paths

exclude_domains

: 正则表达式字符串数组

```
allow_external
```
: 布尔值
```
timeout
```
: 10–150秒
```
include_usage
```
: 布尔值

预期响应字段:

base_url

、

results[]

（URL列表）、

response_time

、

usage

、

request_id

4) crawl → POST /crawl

Use for site traversal with built-in extraction.

bash

curl -sS -X POST "https://api.tavily.com/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false
  }'

Key parameters:

```
url
```
(required)
```
instructions
```
: optional; raises cost and enables
```
chunks_per_source
```
```
chunks_per_source
```
: 1–5 (only with
```
instructions
```
)
```
max_depth
```
,
```
max_breadth
```
,
```
limit
```
: same as map
```
extract_depth
```
:
```
basic
```
|
```
advanced
```
```
format
```
:
```
markdown
```
|
```
text
```

include_images

include_favicon

allow_external

```
timeout
```
: 10–150 seconds
```
include_usage
```
: boolean

Expected response fields:

```
base_url
```
,
```
results[]
```
with
```
url
```
,
```
raw_content
```
,
```
favicon
```
```
response_time
```
,
```
usage
```
,
```
request_id
```

用于站点遍历并内置提取功能。

bash

curl -sS -X POST "https://api.tavily.com/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false
  }'

关键参数:

```
url
```
（必填）
```
instructions
```
: 可选；会增加成本并启用
```
chunks_per_source
```
```
chunks_per_source
```
: 1–5（仅当提供
```
instructions
```
时可用）
```
max_depth
```
、
```
max_breadth
```
、
```
limit
```
: 与map接口相同
```
extract_depth
```
:
```
basic
```
|
```
advanced
```
```
format
```
:
```
markdown
```
|
```
text
```

include_images

、

include_favicon

、

allow_external

```
timeout
```
: 10–150秒
```
include_usage
```
: 布尔值

预期响应字段:

```
base_url
```
、
```
results[]
```
包含
```
url
```
、
```
raw_content
```
、
```
favicon
```
```
response_time
```
、
```
usage
```
、
```
request_id
```

Optional Research Workflow (Deep Investigation)

可选研究工作流（深度调查）

Use when a query needs multi-step analysis and citations.

当查询需要多步骤分析和引用时使用。

create research task → POST /research

创建研究任务 → POST /research

bash

curl -sS -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "input": "<research question>",
    "model": "auto",
    "stream": false,
    "citation_format": "numbered"
  }'

Expected response fields:

request_id

created_at

status

(pending),

input

model

response_time

bash

curl -sS -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "input": "<research question>",
    "model": "auto",
    "stream": false,
    "citation_format": "numbered"
  }'

预期响应字段:

request_id

、

created_at

、

status

（pending）、

input

、

model

、

response_time

get research status → GET /research/{request_id}

获取研究状态 → GET /research/{request_id}

bash

curl -sS -X GET "https://api.tavily.com/research/<request_id>" \
  -H "Authorization: Bearer $TAVILY_API_KEY"

Expected response fields:

```
status
```
:
```
completed
```
```
content
```
: report text or structured object
```
sources[]
```
:
```
{ title, url, favicon }
```

bash

curl -sS -X GET "https://api.tavily.com/research/<request_id>" \
  -H "Authorization: Bearer $TAVILY_API_KEY"

预期响应字段:

```
status
```
:
```
completed
```
```
content
```
: 报告文本或结构化对象
```
sources[]
```
:
```
{ title, url, favicon }
```

streaming research (SSE)

流式研究（SSE）

Set

"stream": true

in the POST body and use curl with

-N

to stream events:

bash

curl -N -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{"input":"<question>","stream":true,"model":"pro"}'

Handle SSE events (tool calls, tool responses, content chunks, sources, done).

在POST请求体中设置

"stream": true

，并使用带

-N

参数的curl来流式接收事件:

bash

curl -N -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{"input":"<question>","stream":true,"model":"pro"}'

处理SSE事件（工具调用、工具响应、内容块、来源、完成）。

Usage Notes

使用注意事项

Treat
```
search
```
,
```
extract
```
,
```
map
```
, and
```
crawl
```
as the primary endpoints for discovery and content retrieval.
Return structured results with URLs, titles, and summaries for easy downstream use.
Default to conservative parameters (
```
search_depth: basic
```
,
```
max_results: 5
```
) unless deeper recall is needed.
Reuse consistent request bodies across calls to keep results predictable.

将
```
search
```
、
```
extract
```
、
```
map
```
和
```
crawl
```
作为发现和内容检索的主要端点。
返回包含URL、标题和摘要的结构化结果，以便于下游使用。
默认使用保守参数（
```
search_depth: basic
```
、
```
max_results: 5
```
），除非需要更深度的召回。
在多次调用中复用一致的请求体，以保持结果的可预测性。

Error Handling

错误处理

If any request returns 401/403, prompt for or re-check
```
TAVILY_API_KEY
```
.
If timeouts occur, reduce
```
max_depth
```
/
```
limit
```
or use
```
search_depth: basic
```
.
If responses are too large, lower
```
max_results
```
or
```
chunks_per_source
```
.

如果任何请求返回401/403状态码，提示用户提供或重新检查
```
TAVILY_API_KEY
```
。
如果发生超时，减少
```
max_depth
```
/
```
limit
```
或使用
```
search_depth: basic
```
。
如果响应结果过大，降低
```
max_results
```
或
```
chunks_per_source
```
的值。