Client Configuration

The TavilyClient (and its asynchronous counterpart AsyncTavilyClient) offer a variety of configuration options to tailor the SDK to your specific network environment, organizational requirements, and tracking needs.

Initialization Arguments

When instantiating a client, you can pass several optional parameters to customize its behavior.

Argument	Type	Default	Description
api_key	str	None	Your Tavily API key. If omitted, the SDK strictly requires the TAVILY_API_KEY environment variable.
proxies	dict[str, str]	None	A dictionary mapping URL schemes ('http', 'https') to proxy URLs. Vital for enterprise environments.
api_base_url	str	"https://api.tavily.com"	Override the default API URL. Useful if routing traffic through a custom API gateway.
client_source	str	"tavily-python"	An identifier sent in the X-Client-Source header. Used to track which SDK/integration is making the call.
project_id	str	None	A specific Project ID sent via the X-Project-ID header to associate usage with a specific project in your Tavily dashboard.

Environment Variables

The SDK is designed to be "environment-aware," automatically respecting several standard and custom environment variables to minimize hardcoded configurations.

• TAVILY_API_KEY: The primary authentication token.
• TAVILY_HTTP_PROXY: A fallback proxy URL for HTTP traffic if proxies is not passed to the constructor.
• TAVILY_HTTPS_PROXY: A fallback proxy URL for HTTPS traffic.
• TAVILY_PROJECT: A fallback project identifier if project_id is not passed to the constructor.

Configuring Proxies

If your application runs inside a corporate network, a VPC without direct internet access, or requires egress IP obfuscation, you will need to route your API requests through a proxy server.

The SDK handles proxy configuration seamlessly for both the sync (requests) and async (httpx) clients.

Example: Explicit Proxy Configuration

from tavily import TavilyClient

# Define your proxies. Include auth credentials in the URL if required.
network_proxies = {
    "http": "http://user:[email protected]:8080",
    "https": "https://user:[email protected]:8080"
}

client = TavilyClient(
    api_key="tvly-YOUR_API_KEY",
    proxies=network_proxies
)

# All requests made by this client will now route through the specified proxy
response = client.search("Current interest rates")

Managing Projects and Usage Tracking

If you are a platform building on top of Tavily, or an organization with multiple internal teams (e.g., a "Data Science" team and a "Customer Support Bot" team), you likely want to track API credit usage separately.

Tavily supports Project IDs. By passing a project_id during initialization, the SDK appends an X-Project-ID header to every HTTP request. This allows the Tavily backend to attribute the cost of that search to the specific project, which you can then view in your billing dashboard.

Example: Multi-Tenant Architecture

from tavily import TavilyClient

# Initialize a client for the HR Support Bot project
hr_client = TavilyClient(project_id="proj_hr_bot_v1")
hr_results = hr_client.search("Latest OSHA workplace regulations")

# Initialize a different client for the Sales Intelligence project
sales_client = TavilyClient(project_id="proj_sales_intel_v2")
sales_results = sales_client.search("Nvidia Q3 earnings report summary")

Alternatively, you can set the TAVILY_PROJECT environment variable in your container or server deployment, allowing you to use a single generic codebase that automatically tracks usage based on where it is deployed.

Best Practices

1. Never hardcode credentials: Always prefer TAVILY_API_KEY over passing the key as a string.
2. Use client_source if you are a library builder: If you are building an open-source framework (like LangChain or LlamaIndex) that wraps this SDK, set client_source="my-awesome-framework". This helps Tavily support engineers debug issues specific to your integration.
3. Global vs Local initialization: Clients are thread-safe. It is generally best practice to initialize your TavilyClient once at the application level and reuse it, which also allows you to take advantage of Session Pooling.