Tavily Purpose
Provide a curl-based interface to Tavily’s REST API for web search, extraction, mapping, crawling, and optional research. Return structured results suitable for LLM workflows and multi-step investigations.
When to Use
Use when a task needs live web information, site extraction, mapping, or crawling.
Use when web searches are needed and no built-in tool is available, or when Tavily’s LLM-friendly output (summaries, chunks, sources, citations) is beneficial.
Use when a task requires structured search results, extraction, or site discovery from Tavily.
Required Environment
Require TAVILY_API_KEY in the environment.
If TAVILY_API_KEY is missing, prompt the user to provide the API key before proceeding.
Base URL and Auth
Base URL: https://api.tavily.com
Authentication: Authorization: Bearer $TAVILY_API_KEY
Content type: Content-Type: application/json
Optional project tracking: add X-Project-ID:
Use for web search with optional answer and content extraction.
Recommended minimal request:
curl -sS -X POST "https://api.tavily.com/search" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"query": "
Key parameters (all optional unless noted):
query (required): search text search_depth: basic | advanced | fast | ultra-fast chunks_per_source: 1–3 (advanced only) max_results: 0–20 topic: general | news | finance time_range: day|week|month|year|d|w|m|y start_date, end_date: YYYY-MM-DD include_answer: false | true | basic | advanced include_raw_content: false | true | markdown | text include_images: boolean include_image_descriptions: boolean include_favicon: boolean include_domains, exclude_domains: string arrays country: country name (general topic only) auto_parameters: boolean include_usage: boolean
Expected response fields:
answer (if requested), results[] with title, url, content, score, raw_content (optional), favicon (optional) response_time, usage, request_id 2) extract → POST /extract
Use for extracting content from specific URLs.
curl -sS -X POST "https://api.tavily.com/extract" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"urls": ["https://example.com/article"],
"query": "
Key parameters:
urls (required): array of URLs query: rerank chunks by intent chunks_per_source: 1–5 (only when query provided) extract_depth: basic | advanced format: markdown | text timeout: 1–60 seconds include_usage: boolean
Expected response fields:
results[] with url, raw_content, images, favicon failed_results[], response_time, usage, request_id 3) map → POST /map
Use for generating a site map (URL discovery only).
curl -sS -X POST "https://api.tavily.com/map" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAVILY_API_KEY" \ -d '{ "url": "https://docs.tavily.com", "max_depth": 1, "max_breadth": 20, "limit": 50, "allow_external": true }'
Key parameters:
url (required) instructions: natural language guidance (raises cost) max_depth: 1–5 max_breadth: 1+ limit: 1+ select_paths, select_domains, exclude_paths, exclude_domains: arrays of regex strings allow_external: boolean timeout: 10–150 seconds include_usage: boolean
Expected response fields:
base_url, results[] (list of URLs), response_time, usage, request_id 4) crawl → POST /crawl
Use for site traversal with built-in extraction.
curl -sS -X POST "https://api.tavily.com/crawl" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TAVILY_API_KEY" \ -d '{ "url": "https://docs.tavily.com", "instructions": "Find all pages about the Python SDK", "max_depth": 1, "max_breadth": 20, "limit": 50, "extract_depth": "basic", "format": "markdown", "include_images": false }'
Key parameters:
url (required) instructions: optional; raises cost and enables chunks_per_source chunks_per_source: 1–5 (only with instructions) max_depth, max_breadth, limit: same as map extract_depth: basic | advanced format: markdown | text include_images, include_favicon, allow_external timeout: 10–150 seconds include_usage: boolean
Expected response fields:
base_url, results[] with url, raw_content, favicon response_time, usage, request_id Optional Research Workflow (Deep Investigation)
Use when a query needs multi-step analysis and citations.
create research task → POST /research
curl -sS -X POST "https://api.tavily.com/research" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"input": "
Expected response fields:
request_id, created_at, status (pending), input, model, response_time
get research status → GET /research/{request_id}
curl -sS -X GET "https://api.tavily.com/research/
Expected response fields:
status: completed content: report text or structured object sources[]: { title, url, favicon } streaming research (SSE)
Set "stream": true in the POST body and use curl with -N to stream events:
curl -N -X POST "https://api.tavily.com/research" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{"input":"
Handle SSE events (tool calls, tool responses, content chunks, sources, done).
Usage Notes Treat search, extract, map, and crawl as the primary endpoints for discovery and content retrieval. Return structured results with URLs, titles, and summaries for easy downstream use. Default to conservative parameters (search_depth: basic, max_results: 5) unless deeper recall is needed. Reuse consistent request bodies across calls to keep results predictable. Error Handling If any request returns 401/403, prompt for or re-check TAVILY_API_KEY. If timeouts occur, reduce max_depth/limit or use search_depth: basic. If responses are too large, lower max_results or chunks_per_source.