SDK Reference

​

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

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

​

Parameters

​

Response format

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

​

Results

​

Image Results

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

​

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

​

Response format

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

​

Successful Results

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

​

Failed Results

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

​

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
}

​

Tavily Hybrid RAG

Tavily Hybrid RAG is an extension of the Tavily Search API built to retrieve relevant data from both the web and an existing database collection. This way, a RAG agent can combine web sources and locally available data to perform its tasks. Additionally, data queried from the web that is not yet in the database can optionally be inserted into it. This will allow similar searches in the future to be answered faster, without the need to query the web again.

​

Parameters

The TavilyHybridClient class is your gateway to Tavily Hybrid RAG. There are a few important parameters to keep in mind when you are instantiating a Tavily Hybrid Client.

​

Methods

search(query, max_results=10, max_local=None, max_foreign=None, save_foreign=False, **kwargs)

Performs a Tavily Hybrid RAG query and returns the retrieved documents as a list[dict] where the documents are sorted by decreasing relevancy to your query. Each returned document will have three properties - content (str), score (float), and origin, which is either local or foreign.

Additional parameters can be provided as keyword arguments (detailed below). The keyword arguments supported by this method are: search_depth, topic, include_raw_content, include_domains,exclude_domains.

​

Setup

​

MongoDB setup

You will need to have a MongoDB collection with a vector search index. You can follow the MongoDB Documentation to learn how to set this up.

​

Cohere API Key

By default, embedding and ranking use the Cohere API, our recommended option. Unless you want to provide a custom embedding and ranking function, you’ll need to get an API key from Cohere and set it as an environment variable named CO_API_KEY

If you decide to stick with Cohere, please note that you’ll need to install the Cohere Python package as well:

pip install cohere

​

Tavily Hybrid RAG Client setup

Once you are done setting up your database, you’ll need to create a MongoDB Client as well as a Tavily Hybrid RAG Client. A minimal setup would look like this:

from pymongo import MongoClient
from tavily import TavilyHybridClient

db = MongoClient("mongodb+srv://YOUR_MONGO_URI")["YOUR_DB"]

hybrid_rag = TavilyHybridClient(
    api_key="tvly-YOUR_API_KEY",
    db_provider="mongodb",
    collection=db.get_collection("YOUR_COLLECTION"),
    index="YOUR_VECTOR_SEARCH_INDEX",
    embeddings_field="YOUR_EMBEDDINGS_FIELD",
    content_field="YOUR_CONTENT_FIELD"
)

​

Usage

Once you create the proper clients, you can easily start searching. A few simple examples are shown below. They assume you’ve followed earlier steps. You can use most of the Tavily Search parameters with Tavily Hybrid RAG as well.

​

Simple Tavily Hybrid RAG example

This example will look for context about Leo Messi on the web and in the local database. Here, we get 5 sources, both from our database and from the web, but we want to exclude unwanted-domain.com from our web search results:

results = hybrid_rag.search("Who is Leo Messi?", max_results=5, exclude_domains=['unwanted-domain.com'])

Here, we want to prioritize the number of local sources, so we will get 2 foreign (web) sources, and 5 sources from our database:

results = hybrid_rag.search("Who is Leo Messi?",  max_local=5, max_foreign=2)

Note: The sum of max_local and max_foreign can exceed max_results, but only the top max_results results will be returned.

​

Adding retrieved data to the database

If you want to add the retrieved data to the database, you can do so by setting the save_foreign parameter to True:

results = hybrid_rag.search("Who is Leo Messi?", save_foreign=True)

This will use our default saving function, which stores the content and its embedding.

​

Examples

​

Sample 1: Using a custom saving function

You might want to add some extra properties to documents you’re inserting or even discard some of them based on custom criteria. This can be done by passing a function to the save_foreign parameter:

def save_document(document):
    if document['score'] < 0.5:
        return None # Do not save documents with low scores

    return {
        'content': document['content'],

         # Save the title and URL in the database
        'site_title': document['title'],
        'site_url': document['url'],

        # Add a new field
        'added_at': datetime.now()
    }

results = hybrid_rag.search("Who is Leo Messi?", save_foreign=save_document)

​

Sample 2: Using a custom embedding function

By default, we use Cohere for our embeddings. If you want to use your own embeddings, can pass a custom embedding function to the TavilyHybridClient:

def my_embedding_function(texts, doc_type): # doc_type will be either 'search_query' or 'search_document'
    return my_embedding_model.encode(texts)

hybrid_rag = TavilyHybridClient(
    # ...
    embedding_function=my_embedding_function
)

​

Sample 3: Using a custom ranking function

Cohere’s rerank model is used by default, but you can pass your own function to the ranking_function parameter:

def my_ranking_function(query, documents, top_n):
    return my_ranking_model.rank(query, documents, top_n)

hybrid_rag = TavilyHybridClient(
    # ...
    ranking_function=my_ranking_function
)