Tavily Search¶

AI-powered web search and URL content extraction via Tavily API. Optimized for LLM applications with clean, relevant results.

Short alias: tav

Highlights¶

AI-synthesised answer + numbered results + sources in one call
Three topic modes: general, news, finance
output_format controls response structure (matching ground convention)
URL content extraction with optional depth control
Batch search and batch extraction with concurrent execution
Deep research via async polling (research())

Functions¶

Function	Description
`tavily.search(query, ...)`	AI-powered web search
`tavily.search_batch(queries, ...)`	Multiple searches concurrently
`tavily.extract(urls, ...)`	Extract raw content from URLs
`tavily.extract_batch(url_sets, ...)`	Extract from multiple URL sets concurrently
`tavily.research(input, ...)`	Deep multi-source research with async polling

Key Parameters¶

search / search_batch¶

Parameter	Type	Description
`query`	str	Search query (required, cannot be empty)
`max_results`	int	Results per query (1-20, default: 5 for search, 2 for batch)
`search_depth`	str	`"basic"` (1 credit, faster) or `"advanced"` (2 credits, default: `"basic"`)
`topic`	str	`"general"`, `"news"`, or `"finance"` (default: `"general"`)
`output_format`	str	`"full"` (answer + results + sources), `"text_only"` (answer only), `"sources_only"` (URL list only). Default: `"full"`
`min_score`	float	Minimum Tavily relevance score to include (0.0–1.0, default: `None`)
`time_range`	str	`"day"`, `"week"`, `"month"`, or `"year"` (default: `None`)
`days`	int	For news topic, how many days back to search (1-30, default: 3)
`include_domains`	list[str]	Restrict results to these domains
`exclude_domains`	list[str]	Exclude results from these domains

extract / extract_batch¶

Parameter	Type	Description
`urls`	list[str]	URLs to extract content from (required, non-empty)
`format`	str	`"markdown"` (default) or `"text"`
`extract_depth`	str	`"basic"` (1 credit/5 URLs) or `"advanced"` (2 credits/5 URLs, default: `"basic"`)
`url_sets`	list	For `extract_batch`: list of URL lists or `(url_list, label)` tuples

research¶

Parameter	Type	Description
`input`	str	Research question or task (required, cannot be empty)
`model`	str	`"mini"` (5 credits), `"pro"` (20 credits), `"auto"` (default)
`timeout_seconds`	int	Max seconds to wait for completion (default: 300)

Requires¶

TAVILY_API_KEY in secrets.yaml

Configuration¶

Required¶

TAVILY_API_KEY must be set in secrets.yaml.

Optional¶

Key	Type	Default	Description
`tools.tavily.timeout`	float	`60.0`	Request timeout in seconds. Range: `1.0-300.0`.

tools:
  tavily:
    timeout: 60.0

Defaults¶

If tools.tavily is omitted, Tavily uses the built-in timeout shown above.

Examples¶

# Basic web search — AI answer + results + sources
tavily.search(query="Python asyncio best practices")

# AI answer only
tavily.search(query="what is uv package manager", output_format="text_only")

# Sources list only
tavily.search(query="FastAPI documentation", output_format="sources_only")

# News search, recent results, filter by relevance score
tavily.search(query="latest AI model releases", topic="news",
              time_range="week", min_score=0.7)

# Finance search with domain filter
tavily.search(query="Apple earnings Q1 2025", topic="finance",
              include_domains=["reuters.com", "bloomberg.com"])

# Extract content from a URL
tavily.extract(urls=["https://docs.python.org/3/library/asyncio.html"])

# Extract from multiple URLs (failed URLs listed separately)
tavily.extract(urls=[
    "https://fastapi.tiangolo.com/",
    "https://pydantic-docs.helpmanual.io/",
])

# Batch extraction with labels
tavily.extract_batch(url_sets=[
    (["https://docs.astral.sh/uv/"], "uv Docs"),
    (["https://docs.pydantic.dev/"], "Pydantic Docs"),
])

# Batch search (concurrent execution)
tavily.search_batch(queries=["sqlalchemy 2.0", "pydantic v2", "httpx async"])

# Batch with custom labels and sources only
tavily.search_batch(queries=[
    ("Python 3.13 new features", "Python 3.13"),
    ("uv python package manager", "uv"),
], output_format="sources_only")

# Deep research (async polling, may take minutes)
tavily.research(input="How does Rust's borrow checker work?")
tavily.research(input="State of LLM context scaling 2025", model="pro", timeout_seconds=600)