Client API Reference

This page outlines the core method signatures for the Tavily SDK. Both TavilyClient (synchronous) and AsyncTavilyClient (asynchronous) share identical method signatures and parameter names.

Note: If using AsyncTavilyClient, all methods (except .close()) must be prefixed with await.

---

.search(...)

The primary method for executing queries against the web.

def search(
    query: str,
    search_depth: Literal["basic", "advanced", "fast", "ultra-fast"] = None,
    topic: Literal["general", "news", "finance"] = None,
    time_range: Literal["day", "week", "month", "year"] = None,
    start_date: str = None,
    end_date: str = None,
    days: int = None,
    max_results: int = None,
    include_domains: Sequence[str] = None,
    exclude_domains: Sequence[str] = None,
    include_answer: Union[bool, Literal["basic", "advanced"]] = None,
    include_raw_content: Union[bool, Literal["markdown", "text"]] = None,
    include_images: bool = None,
    timeout: float = 60,
    country: str = None,
    auto_parameters: bool = None,
    include_favicon: bool = None,
    include_usage: bool = None,
    **kwargs
) -> dict

Returns Dictionary Schema:

• query (str): The executed query.
• results (List[dict]): Array of result objects containing title, url, content, score, and optionally raw_content.
• answer (str): Populated if include_answer=True.
• images (List[str]): Populated if include_images=True.
• response_time (float): Processing time in seconds.

---

.extract(...)

Extracts and parses clean content from known URLs.

def extract(
    urls: Union[List[str], str],
    include_images: bool = None,
    extract_depth: Literal["basic", "advanced"] = None,
    format: Literal["markdown", "text"] = None,
    timeout: float = 30,
    include_favicon: bool = None,
    include_usage: bool = None,
    query: str = None,
    chunks_per_source: int = None,
    **kwargs
) -> dict

Returns Dictionary Schema:

• results (List[dict]): Array of successful extractions containing url and raw_content.
• failed_results (List[dict]): Array of failures containing url and error.

---

.crawl(...)

Traverses a website extracting content based on parameters and AI instructions.

def crawl(
    url: str,
    max_depth: int = None,
    max_breadth: int = None,
    limit: int = None,
    instructions: str = None,
    select_paths: Sequence[str] = None,
    select_domains: Sequence[str] = None,
    exclude_paths: Sequence[str] = None,
    exclude_domains: Sequence[str] = None,
    allow_external: bool = None,
    include_images: bool = None,
    extract_depth: Literal["basic", "advanced"] = None,
    format: Literal["markdown", "text"] = None,
    timeout: float = 150,
    include_favicon: bool = None,
    include_usage: bool = None,
    chunks_per_source: int = None,
    **kwargs
) -> dict

Returns Dictionary Schema:

• results (List[dict]): Extracted pages matching instructions.

---

.map(...)

Maps a website's structural blueprint without extracting page content.

def map(
    url: str,
    max_depth: int = None,
    max_breadth: int = None,
    limit: int = None,
    instructions: str = None,
    select_paths: Sequence[str] = None,
    select_domains: Sequence[str] = None,
    exclude_paths: Sequence[str] = None,
    exclude_domains: Sequence[str] = None,
    allow_external: bool = None,
    include_images: bool = None,
    timeout: float = 150,
    include_usage: bool = None,
    **kwargs
) -> dict

Returns Dictionary Schema:

• results (List[str]): Array of discovered URL strings.

---

.research(...)

Initiates a multi-step autonomous research agent.

def research(
    input: str,
    model: Literal["mini", "pro", "auto"] = None,
    output_schema: dict = None,
    stream: bool = False,
    citation_format: Literal["numbered", "mla", "apa", "chicago"] = "numbered",
    timeout: Optional[float] = None,
    **kwargs
) -> Union[dict, Generator[bytes, None, None]]
# Note: Returns an AsyncGenerator in AsyncTavilyClient when stream=True

Returns (if stream=False):

• A dictionary containing request_id, created_at, status, input, and model.

---

.get_research(...)

Retrieves the final results of a background research task by its ID.

def get_research(request_id: str) -> dict

Returns Dictionary Schema:

• request_id (str): The queried ID.
• status (str): Will be "pending", "completed", or "failed".
• content (str): The synthesized research report (if completed).
• sources (List[dict]): URLs used to compile the report.