Tavily Python SDK

In enterprise environments using API gateways, you can pass a pre-configured requests.Session (sync) or httpx.AsyncClient (async) to TavilyClient or AsyncTavilyClient instead of an api_key.

Key Behaviors:

• If a custom session/client is provided, api_key is optional.
• Custom session headers take precedence over SDK defaults.
• Custom session proxies take precedence over SDK proxy settings.
• Lifecycle: The SDK will not close externally-provided sessions; you are responsible for managing their lifecycle.

Sync Example:

import requests
from tavily import TavilyClient

session = requests.Session()
session.headers["Authorization"] = "Bearer your-gateway-token"

client = TavilyClient(session=session, api_base_url="https://your-gateway.com/tavily")
response = client.search("latest AI research")

Async Example:

import httpx
from tavily import AsyncTavilyClient

custom_client = httpx.AsyncClient(headers={"Authorization": "Bearer token"}, base_url="https://your-gateway.com/tavily")
client = AsyncTavilyClient(client=custom_client)
response = await client.search("latest AI research")

import requests
from tavily import TavilyClient

# Pre-configure a session with your gateway's auth
session = requests.Session()
session.headers["Authorization"] = "Bearer your-gateway-token"
session.headers["X-Subscription-Key"] = "your-subscription-key"

# No Tavily API key needed — auth is handled by the session
client = TavilyClient(
    session=session,
    api_base_url="https://your-gateway.com/tavily",
)

response = client.search("latest AI research")

The research() method creates comprehensive research reports with automatic source gathering and analysis.

Workflow:

1. Call research() to create a task. It returns a request_id.
2. Use get_research(request_id) to retrieve the results once the task is processed.

Parameters for research():

• input: The research topic.
• model: The model to use (e.g., pro).
• citation_format: Format for citations (e.g., apa).
• stream: If True, returns a generator that yields chunks of the report.

Example (Polling):

response = tavily_client.research(input="AI developments", model="pro")
request_id = response["request_id"]
result = tavily_client.get_research(request_id)
print(result['content'])

Example (Streaming):

stream = tavily_client.research(input="AI developments", model="pro", stream=True)
for chunk in stream:
    print(chunk.decode('utf-8'))

from tavily import TavilyClient

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

# Step 2. Creating a research task
response = tavily_client.research(
    input="Research the latest developments in AI",
    model="pro",
    citation_format="apa"
)

# Step 3. Retrieving the research results
request_id = response["request_id"]
result = tavily_client.get_research(request_id)

# Step 4. Printing the research report
print(f"Status: {result['status']}")
print(f"Content: {result['content']}")
print(f"Sources: {len(result['sources'])} sources found")

The crawl() method traverses a website's content starting from a base URL.

Note: Crawl is currently available on an invite-only basis.

Parameters:

• url: The starting URL.
• max_depth: Maximum depth of traversal.
• limit: Maximum number of pages to crawl.
• instructions: Text instructions to guide the crawler (e.g., to find specific topics).

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

start_url = "https://wikipedia.org/wiki/Lemon"

response = tavily_client.crawl(
    url=start_url,
    max_depth=3,
    limit=50,
    instructions="Find all pages on citrus fruits"
)

for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"Snippet: {result['raw_content'][:200]}...\n")

from tavily import TavilyClient

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

# Step 2. Defining the starting URL
start_url = "https://wikipedia.org/wiki/Lemon"

# Step 3. Executing the crawl request with instructions to surface only pages about citrus fruits
response = tavily_client.crawl(
    url=start_url,
    max_depth=3,
    limit=50,
    instructions="Find all pages on citrus fruits"
)

# Step 4. Printing pages matching the query
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"Snippet: {result['raw_content'][:200]}...\n")

Use extract(urls=..., include_images=...) to retrieve raw content from a list of URLs (up to 20 simultaneously).

Response Structure:

• results: A list of dictionaries containing url, raw_content, and images.
• failed_results: A list of URLs that could not be extracted.

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

urls = [
    "https://en.wikipedia.org/wiki/Artificial_intelligence",
    "https://en.wikipedia.org/wiki/Machine_learning"
]

response = tavily_client.extract(urls=urls, include_images=True)

for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"Raw Content: {result['raw_content']}")
    print(f"Images: {result['images']}\n")

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",
    "https://en.wikipedia.org/wiki/Quantum_computing",
    "https://en.wikipedia.org/wiki/Climate_change"
] # You can provide up to 20 URLs simultaneously

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

# Step 4. Printing the extracted raw content
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"Raw Content: {result['raw_content']}")
    print(f"Images: {result['images']}\n")

# Note that URLs that could not be extracted will be stored in response["failed_results"]

The map() method discovers and visualizes the structure of a website starting from a base URL.

Parameters:

• url: The starting URL.
• max_depth: Maximum depth of traversal.
• limit: Maximum number of pages to map.
• instructions: Text instructions to focus the mapping on specific content.

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

start_url = "https://wikipedia.org/wiki/Lemon"

response = tavily_client.map(
    url=start_url,
    max_depth=2,
    limit=30,
    instructions="Find pages on citrus fruits"
)

for result in response["results"]:
    print(f"URL: {result['url']}")

from tavily import TavilyClient

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

# Step 2. Defining the starting URL
start_url = "https://wikipedia.org/wiki/Lemon"

# Step 3. Executing the map request with parameters to focus on specific pages
response = tavily_client.map(
    url=start_url,
    max_depth=2,
    limit=30,
    instructions="Find pages on citrus fruits"
)

# Step 4. Printing the site structure
for result in response["results"]:
    print(f"URL: {result['url']}")