Python

Instantiating a client

To interact with Tavily in Python, you must instatiate a client with your API key. For greater flexibility, we provide both a synchronous and an asynchronous client class.

Once you have instantiated a client, call one of our supported methods (detailed below) to access the API.

Synchronous Client

from tavily import TavilyClient

client = TavilyClient("tvly-YOUR_API_KEY")

Asynchronous Client

from tavily import AsyncTavilyClient

client = AsyncTavilyClient("tvly-YOUR_API_KEY")

Tavily Search

NEW! Try our interactive API Playground to see each parameter in action, and generate ready-to-use Python snippets.

You can access Tavily Search in Python through the client’s search function.

Parameters

Parameter	Type	Description	Default
`query` (required)	`str`	The query to run a search on.
`search_depth`	`str`	The depth of the search. It can be `"basic"` or `"advanced"`.	`"basic"`
`topic`	`str`	The category of the search. Determines which agent will be used. Supported values are `"general"` and `"news"`.	`"general"`
`days`	`int`	The number of days back from the current date to include in the results. Available only when using the `"news"` topic.	`3`
`time_range`	`str`	The time range back from the current date. Accepted values include `"day"`, `"week"`, `"month"`, `"year"` or shorthand values `"d"`, `"w"`, `"m"`, `"y"`.
`max_results`	`int`	The maximum number of search results to return. It must be between `0` and `20`.	`5`
`include_images`	`bool`	Include a list of query-related images in the response.	`False`
`include_image_descriptions`	`bool`	Include a list of query-related images and their descriptions in the response.	`False`
`include_answer`	`bool` or `str`	Include an answer to the query generated by an LLM based on search results. A `"basic"` (or `True`) answer is quick but less detailed; an `"advanced"` answer is more detailed.	`False`
`include_raw_content`	`bool`	Include the cleaned and parsed HTML content of each search result.	`False`
`include_domains`	`list[str]`	A list of domains to specifically include in the search results.	`[]`
`exclude_domains`	`list[str]`	A list of domains to specifically exclude from the search results.	`[]`

Response format

The response object you receive will be in the following format:

Key	Type	Description
`results`	`list[Result]`	A list of sorted search results ranked by relevancy.
`query`	`str`	Your search query.
`response_time`	`float`	Your search result response time.
`answer` (optional)	`str`	The answer to your search query, generated by an LLM based on Tavily’s search results. This is only available if `include_answer` is set to `True`.
`images` (optional)	`list[str]` or `list[ImageResult]`	This is only available if `include_images` is set to `True`. A list of query-related image URLs. If `include_image_descriptions` is set to `True`, each entry will be an `ImageResult`.

Results

`Key`	`Type`	Description
`title`	`str`	The title of the search result.
`url`	`str`	The URL of the search result.
`content`	`str`	The most query-related content from the scraped URL. Tavily uses proprietary AI to extract the most relevant content based on context quality and size.
`score`	`float`	The relevance score of the search result.
`raw_content` (optional)	`str`	The parsed and cleaned HTML content of the site. This is only available if `include_raw_content` is set to `True`.
`published_date` (optional)	`str`	The publication date of the source. This is only available if the search `topic` is set to `"news"`.

Image Results

If includeImageDescriptions is set to true, each image in the images list will be in the following ImageResult format:

Key	Type	Description
`url`	`string`	The URL of the image.
`description`	`string`	An LLM-generated description of the image.

Example

from tavily import TavilyClient

# Step 1. Instantiating your TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# Step 2. Executing the search request
response = tavily_client.search("Who is Leo Messi?", include_images=True, include_image_descriptions=True)

# Step 3. Printing the search results
print(response)

{
  "query": "Who is Leo Messi?",
  "images": [ 
    {
      "url": "Image 1 URL",
      "description": "Image 1 Description",  
    },
    {
      "url": "Image 2 URL",
      "description": "Image 2 Description",
    },
    {
      "url": "Image 3 URL",
      "description": "Image 3 Description",
    },
    {
      "url": "Image 4 URL",
      "description": "Image 4 Description",
    },
    {
      "url": "Image 5 URL",
      "description": "Image 5 Description",
    }
  ],
  "results": [
    {
      "title": "Source 1 Title",
      "url": "Source 1 URL",
      "content": "Source 1 Content",
      "score": 0.99 
    },
    {
      "title": "Source 2 Title",
      "url": "Source 2 URL",
      "content": "Source 2 Content",
      "score": 0.97
    }
  ],
  "response_time": 1.09 
}

Tavily Extract

You can access Tavily Extract in Python through the client’s extract function.

Parameters

Parameter	Type	Description	Default
`urls` (required)	`str` or `list[str]`	The URL (or URLs) you want to extract. If a list is provided, it must not contain more than 20 URLs.
`include_images`	`bool`	Include a list of images extracted from the URLs in the response.	`False`
`extract_depth`	`str`	The depth of the extraction process. You may experience higher latency with `"advanced"` extraction, but it offers a higher success rate and retrieves more data from the URL (e.g., tables, embedded content). `"basic"` extraction costs 1 API Credit per 5 successful URL extractions, while `advanced` extraction costs 2 API Credits per 5 successful URL extractions.	`"basic"`

Response format

The response object you receive will be in the following format:

Key	Type	Description
`results`	`list[SuccessfulResult]`	A list of extracted content.
`failed_results`	`list[FailedResult]`	A list of URLs that could not be processed.
`response_time`	`float`	The search result response time.

Successful Results

Each successful result in the results list will be in the following SuccessfulResult format:

Key	Type	Description
`url`	`str`	The URL of the webpage.
`raw_content`	`str`	The raw content extracted.
`images` (optional)	`list[str]`	This is only available if `include_images` is set to `True`. A list of extracted image URLs.

Failed Results

Each failed result in the results list will be in the following FailedResult format:

Key	Type	Description
`url`	`str`	The URL that failed.
`error`	`str`	An error message describing why it could not be processed.

Example

from tavily import TavilyClient

# Step 1. Instantiating your TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# Step 2. Defining the list of URLs to extract content from
urls = [
    "https://en.wikipedia.org/wiki/Artificial_intelligence",
    "https://en.wikipedia.org/wiki/Machine_learning",
    "https://en.wikipedia.org/wiki/Data_science",
]

# Step 3. Executing the extract request
response = tavily_client.extract(urls=urls, include_images=True)

# Step 4. Printing the extracted raw content
print(response)

{
    "results": [
        {
            "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
            "raw_content": "URL 1 raw content",
            "images": [
                "Image 1 URL",
                "Image 2 URL"
            ]
        },
        {
            "url": "https://en.wikipedia.org/wiki/Machine_learning",
            "raw_content": "URL 2 raw content",
            "images": [
                "Image 3 URL",
                "Image 4 URL"
            ]
        },
        {
            "url": "https://en.wikipedia.org/wiki/Data_science",
            "raw_content": "URL 3 raw content",
            "images": [
                "Image 5 URL",
                "Image 6 URL"
            ]
        }
    ],
    "failed_results": [],
    "response_time": 1.23
}

Get Started

API Reference

Instantiating a client

Synchronous Client

Asynchronous Client

Tavily Search

Parameters

Response format

Results

Image Results

Example

Tavily Extract

Parameters

Response format

Successful Results

Failed Results

Example

Get Started

API Reference

​Instantiating a client

​Synchronous Client

​Asynchronous Client

​Tavily Search

​Parameters

​Response format

​Results

​Image Results

​Example

​Tavily Extract

​Parameters

​Response format

​Successful Results

​Failed Results

​Example

Instantiating a client

Synchronous Client

Asynchronous Client

Tavily Search

Parameters

Response format

Results

Image Results

Example

Tavily Extract

Parameters

Response format

Successful Results

Failed Results

Example