Access the Tavily API with managed API key authentication. Perform AI-powered web searches, extract content from URLs, crawl websites, map site structure, and run in-depth research tasks.
Reference
Search
Perform AI-powered web search with optional answer generation.
POST /tavily/search
Content-Type: application/json
{
"query": "What is artificial intelligence?",
"max_results": 5
}Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search query string |
| max_results | integer | No | Number of results (0-20, default 5) |
| search_depth | string | No | basic, advanced, fast, ultra-fast (default: basic) |
| topic | string | No | general or news (default: general) |
| include_answer | boolean/string | No | true, false, basic, advanced |
| include_raw_content | boolean/string | No | true, false, markdown, text |
| include_images | boolean | No | Include image results |
| include_domains | array | No | Only search these domains (max 300) |
| exclude_domains | array | No | Exclude these domains (max 150) |
| time_range | string | No | day, week, month, year |
| start_date | string | No | Filter by date (YYYY-MM-DD) |
| end_date | string | No | Filter by date (YYYY-MM-DD) |
Response:
{
"query": "What is artificial intelligence?",
"answer": "Artificial intelligence (AI) is...",
"results": [
{
"title": "What is AI?",
"url": "https://example.com/ai",
"content": "AI is a branch of computer science...",
"score": 0.95
}
],
"response_time": 0.55
}Extract
Extract content from one or more URLs.
POST /tavily/extract
Content-Type: application/json
{
"urls": ["https://example.com/article"],
"format": "markdown"
}Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| urls | string/array | Yes | URL or array of URLs to extract |
| query | string | No | User intent for reranking content |
| chunks_per_source | integer | No | Max chunks per source (1-5, default 3) |
| extract_depth | string | No | basic or advanced (default: basic) |
| format | string | No | markdown or text (default: markdown) |
| include_images | boolean | No | Include extracted images |
| timeout | float | No | Max wait time in seconds (1-60) |
Response:
{
"results": [
{
"url": "https://example.com/article",
"raw_content": "# Article Title\n\nContent in markdown...",
"images": [],
"favicon": "https://example.com/favicon.ico"
}
],
"failed_results": [],
"response_time": 0.01
}Map
Discover URLs from a website without extracting content.
POST /tavily/map
Content-Type: application/json
{
"url": "https://example.com",
"limit": 20
}Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | Root URL to begin mapping |
| instructions | string | No | Natural language guidance for crawler |
| max_depth | integer | No | Exploration depth (1-5, default 1) |
| max_breadth | integer | No | Links per page level (1-500, default 20) |
| limit | integer | No | Total links to process (default 50) |
| select_paths | array | No | Regex patterns for URL inclusion |
| exclude_paths | array | No | Regex patterns for URL exclusion |
| allow_external | boolean | No | Include external links (default true) |
| timeout | float | No | Max wait time (10-150 seconds) |
Response:
{
"base_url": "https://example.com",
"results": [
"https://example.com/about",
"https://example.com/products",
"https://example.com/contact"
],
"response_time": 0.1
}Crawl
Crawl a website and extract content from discovered pages.
POST /tavily/crawl
Content-Type: application/json
{
"url": "https://example.com",
"limit": 10,
"max_depth": 2
}Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | Root URL to begin crawl |
| instructions | string | No | Natural language guidance (2x cost) |
| chunks_per_source | integer | No | Max snippets per source (1-5, default 3) |
| max_depth | integer | No | Exploration depth (1-5, default 1) |
| max_breadth | integer | No | Links per page level (1-500, default 20) |
| limit | integer | No | Total links to process (default 50) |
| select_paths | array | No | Regex patterns for URL inclusion |
| exclude_paths | array | No | Regex patterns for URL exclusion |
| allow_external | boolean | No | Include external links (default true) |
| extract_depth | string | No | basic or advanced (default: basic) |
| format | string | No | markdown or text (default: markdown) |
| timeout | float | No | Max wait time (10-150 seconds) |
Response:
{
"base_url": "https://example.com",
"results": [
{
"url": "https://example.com/about",
"raw_content": "# About Us\n\nContent...",
"favicon": "https://example.com/favicon.ico"
}
],
"response_time": 0.09
}Create Research Task
POST /tavily/research
Content-Type: application/json
{
"input": "What are the latest developments in AI safety?",
"model": "mini"
}Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| input | string | Yes | Research task or question |
| model | string | No | mini, pro, or auto (default: auto) |
| stream | boolean | No | Stream results via SSE (default: false) |
| output_schema | object | No | JSON Schema for structured output |
| citation_format | string | No | numbered, mla, apa, chicago |
Response:
{
"request_id": "582a6eec-9a10-43ba-830f-d9a1aeb19f07",
"status": "pending",
"input": "What are the latest developments in AI safety?",
"model": "mini",
"created_at": "2026-03-08T11:36:12.674507+00:00",
"response_time": 0.05
}Get Research Task
GET /tavily/research/{request_id}Response (completed):
{
"request_id": "582a6eec-9a10-43ba-830f-d9a1aeb19f07",
"status": "completed",
"content": "## AI Safety Developments\n\nResearch findings...",
"sources": [
{
"title": "Source Title",
"url": "https://example.com/source",
"favicon": "https://example.com/favicon.ico"
}
],
"created_at": "2026-03-08T11:36:12.674507+00:00",
"response_time": 45
}Status values: pending, in_progress, completed, failed