deepset-ai--haystack/docs-website/reference_versioned_docs/version-2.19/integrations-api/tavily.md

title, id, description, slug

title	id	description	slug
Tavily	integrations-tavily	Tavily integration for Haystack	/integrations-tavily

haystack_integrations.components.websearch.tavily.tavily_websearch

TavilyWebSearch

A component that uses Tavily to search the web and return results as Haystack Documents.

This component wraps the Tavily Search API, enabling web search queries that return structured documents with content and links.

Tavily is an AI-powered search API optimized for LLM applications. You need a Tavily API key from tavily.com.

Usage example

from haystack_integrations.components.websearch.tavily import TavilyWebSearch
from haystack.utils import Secret

websearch = TavilyWebSearch(
    api_key=Secret.from_env_var("TAVILY_API_KEY"),
    top_k=5,
)
result = websearch.run(query="What is Haystack by deepset?")
documents = result["documents"]
links = result["links"]

init

__init__(
    api_key: Secret = Secret.from_env_var("TAVILY_API_KEY"),
    top_k: int | None = 10,
    search_params: dict[str, Any] | None = None,
) -> None

Initialize the TavilyWebSearch component.

Parameters:

• api_key (Secret) – API key for Tavily. Defaults to the TAVILY_API_KEY environment variable.
• top_k (int | None) – Maximum number of results to return.
• search_params (dict[str, Any] | None) – Additional parameters passed to the Tavily search API. See the Tavily API reference for available options. Supported keys include: search_depth, include_answer, include_raw_content, include_domains, exclude_domains.

warm_up

warm_up() -> None

Initialize the Tavily sync and async clients.

Called automatically on first use. Can be called explicitly to avoid cold-start latency.

run

run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]

Search the web using Tavily and return results as Documents.

Parameters:

• query (str) – Search query string.
• search_params (dict[str, Any] | None) – Optional per-run override of search parameters. If provided, fully replaces the init-time search_params.

Returns:

• dict[str, Any] – A dictionary with:
• documents: List of Documents containing search result content.
• links: List of URLs from the search results.

run_async

run_async(
    query: str, search_params: dict[str, Any] | None = None
) -> dict[str, Any]

Asynchronously search the web using Tavily and return results as Documents.

Parameters:

• query (str) – Search query string.
• search_params (dict[str, Any] | None) – Optional per-run override of search parameters. If provided, fully replaces the init-time search_params.

Returns:

• dict[str, Any] – A dictionary with:
• documents: List of Documents containing search result content.
• links: List of URLs from the search results.