Skip to main content

​
Base URL

The base URL for all requests to the Tavily API is: 
https://api.tavily.com

​
Authentication

All Tavily endpoints are authenticated using API keys. Get your free API key. 
curl -X POST https://api.tavily.com/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tvly-YOUR_API_KEY" \
  -d '{"query": "Who is Leo Messi?"}'

​
Endpoints

/searchTavily’s powerful web search API.

/extractTavily’s powerful content extraction API.

/crawl , /mapTavily’s intelligent sitegraph navigation and extraction tools.

/researchTavily’s comprehensive research API for in-depth analysis.

​
Project Tracking

You can optionally attach a Project ID to your API requests to organize and track usage by project. This is useful when a single API key is used across multiple projects or applications. To attach a project to your request, add the X-Project-ID header: 
curl -X POST https://api.tavily.com/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tvly-YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id" \
  -d '{"query": "Who is Leo Messi?"}'
Key features:
  • An API key can be associated with multiple projects
  • Filter requests by project in the /logs endpoint and platform usage dashboard
  • Helps organize and track where requests originate from
When using the SDKs, you can specify a project using the project_id parameter when instantiating the client, or by setting the TAVILY_PROJECT environment variable.

​
Session Tracking

You can optionally include session and anonymized user identifiers in your API requests as HTTP headers. Tavily uses these identifiers for attribution and analytics across multi-step user interactions and agent workflows. 
curl -X POST https://api.tavily.com/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tvly-YOUR_API_KEY" \
  -H "X-Session-Id: 5874812a-2e9b-43ea-8978-6cc9225b587b" \
  -H "X-Human-Id: h_4f9ac" \
  -d '{"query": "Who is Leo Messi?"}'
Headers:
  • X-Session-Id — opaque identifier for a session of related requests. Lets you group multiple calls together (e.g. all requests from one user task or conversation).
  • X-Human-Id — opaque identifier for the end-user behind the request. Useful when a single API key serves many human users — it helps Tavily better understand multi-step interactions and improve response quality. For security, Tavily hashes human IDs before processing or storing them.
When you use the Tavily MCP server or remote MCP server, X-Session-Id is populated automatically — you don’t need to set it yourself. X-Human-Id can’t be generated by the MCP server on its own, so it’s only forwarded if your agent or developer provides it. See the MCP documentation for details.