1  ---
  2  title: "Tavily"
  3  id: integrations-tavily
  4  description: "Tavily integration for Haystack"
  5  slug: "/integrations-tavily"
  6  ---
  7  
  8  
  9  ## haystack_integrations.components.websearch.tavily.tavily_websearch
 10  
 11  ### TavilyWebSearch
 12  
 13  A component that uses Tavily to search the web and return results as Haystack Documents.
 14  
 15  This component wraps the Tavily Search API, enabling web search queries that return
 16  structured documents with content and links.
 17  
 18  Tavily is an AI-powered search API optimized for LLM applications. You need a Tavily
 19  API key from [tavily.com](https://tavily.com).
 20  
 21  ### Usage example
 22  
 23  ```python
 24  from haystack_integrations.components.websearch.tavily import TavilyWebSearch
 25  from haystack.utils import Secret
 26  
 27  websearch = TavilyWebSearch(
 28      api_key=Secret.from_env_var("TAVILY_API_KEY"),
 29      top_k=5,
 30  )
 31  result = websearch.run(query="What is Haystack by deepset?")
 32  documents = result["documents"]
 33  links = result["links"]
 34  ```
 35  
 36  #### __init__
 37  
 38  ```python
 39  __init__(
 40      api_key: Secret = Secret.from_env_var("TAVILY_API_KEY"),
 41      top_k: int | None = 10,
 42      search_params: dict[str, Any] | None = None,
 43  ) -> None
 44  ```
 45  
 46  Initialize the TavilyWebSearch component.
 47  
 48  **Parameters:**
 49  
 50  - **api_key** (<code>Secret</code>) – API key for Tavily. Defaults to the `TAVILY_API_KEY` environment variable.
 51  - **top_k** (<code>int | None</code>) – Maximum number of results to return.
 52  - **search_params** (<code>dict\[str, Any\] | None</code>) – Additional parameters passed to the Tavily search API.
 53    See the [Tavily API reference](https://docs.tavily.com/docs/tavily-api/rest_api)
 54    for available options. Supported keys include: `search_depth`, `include_answer`,
 55    `include_raw_content`, `include_domains`, `exclude_domains`.
 56  
 57  #### warm_up
 58  
 59  ```python
 60  warm_up() -> None
 61  ```
 62  
 63  Initialize the Tavily sync and async clients.
 64  
 65  Called automatically on first use. Can be called explicitly to avoid cold-start latency.
 66  
 67  #### run
 68  
 69  ```python
 70  run(query: str, search_params: dict[str, Any] | None = None) -> dict[str, Any]
 71  ```
 72  
 73  Search the web using Tavily and return results as Documents.
 74  
 75  **Parameters:**
 76  
 77  - **query** (<code>str</code>) – Search query string.
 78  - **search_params** (<code>dict\[str, Any\] | None</code>) – Optional per-run override of search parameters.
 79    If provided, fully replaces the init-time `search_params`.
 80  
 81  **Returns:**
 82  
 83  - <code>dict\[str, Any\]</code> – A dictionary with:
 84  - `documents`: List of Documents containing search result content.
 85  - `links`: List of URLs from the search results.
 86  
 87  #### run_async
 88  
 89  ```python
 90  run_async(
 91      query: str, search_params: dict[str, Any] | None = None
 92  ) -> dict[str, Any]
 93  ```
 94  
 95  Asynchronously search the web using Tavily and return results as Documents.
 96  
 97  **Parameters:**
 98  
 99  - **query** (<code>str</code>) – Search query string.
100  - **search_params** (<code>dict\[str, Any\] | None</code>) – Optional per-run override of search parameters.
101    If provided, fully replaces the init-time `search_params`.
102  
103  **Returns:**
104  
105  - <code>dict\[str, Any\]</code> – A dictionary with:
106  - `documents`: List of Documents containing search result content.
107  - `links`: List of URLs from the search results.