Tavily Map

Tavily Map traverses websites like a graph and can explore hundreds of paths in parallel with intelligent discovery to generate comprehensive site maps.

POST /map

Python SDK

Python

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
response = tavily_client.map("https://docs.tavily.com")

print(response)

const { tavily } = require("@tavily/core");

const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
const response = await tvly.map("https://docs.tavily.com");

console.log(response);

curl --request POST \
  --url https://api.tavily.com/map \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "docs.tavily.com",
  "instructions": "Find all pages about the Python SDK",
  "max_depth": 1,
  "max_breadth": 20,
  "limit": 50,
  "select_paths": null,
  "select_domains": null,
  "exclude_paths": null,
  "exclude_domains": null,
  "allow_external": true,
  "timeout": 150,
  "include_usage": false
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tavily.com/map",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => 'docs.tavily.com',
    'instructions' => 'Find all pages about the Python SDK',
    'max_depth' => 1,
    'max_breadth' => 20,
    'limit' => 50,
    'select_paths' => null,
    'select_domains' => null,
    'exclude_paths' => null,
    'exclude_domains' => null,
    'allow_external' => true,
    'timeout' => 150,
    'include_usage' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tavily.com/map"

	payload := strings.NewReader("{\n  \"url\": \"docs.tavily.com\",\n  \"instructions\": \"Find all pages about the Python SDK\",\n  \"max_depth\": 1,\n  \"max_breadth\": 20,\n  \"limit\": 50,\n  \"select_paths\": null,\n  \"select_domains\": null,\n  \"exclude_paths\": null,\n  \"exclude_domains\": null,\n  \"allow_external\": true,\n  \"timeout\": 150,\n  \"include_usage\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tavily.com/map")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"docs.tavily.com\",\n  \"instructions\": \"Find all pages about the Python SDK\",\n  \"max_depth\": 1,\n  \"max_breadth\": 20,\n  \"limit\": 50,\n  \"select_paths\": null,\n  \"select_domains\": null,\n  \"exclude_paths\": null,\n  \"exclude_domains\": null,\n  \"allow_external\": true,\n  \"timeout\": 150,\n  \"include_usage\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tavily.com/map")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"docs.tavily.com\",\n  \"instructions\": \"Find all pages about the Python SDK\",\n  \"max_depth\": 1,\n  \"max_breadth\": 20,\n  \"limit\": 50,\n  \"select_paths\": null,\n  \"select_domains\": null,\n  \"exclude_paths\": null,\n  \"exclude_domains\": null,\n  \"allow_external\": true,\n  \"timeout\": 150,\n  \"include_usage\": false\n}"

response = http.request(request)
puts response.read_body

200

{
  "base_url": "docs.tavily.com",
  "results": [
    "https://docs.tavily.com/welcome",
    "https://docs.tavily.com/documentation/api-credits",
    "https://docs.tavily.com/documentation/about"
  ],
  "response_time": 1.23,
  "usage": {
    "credits": 1
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174111"
}

{
  "detail": {
    "error": "[400] No starting url provided"
  }
}

{
  "detail": {
    "error": "Unauthorized: missing or invalid API key."
  }
}

{
  "detail": {
    "error": "[403] URL is not supported"
  }
}

{
  "detail": {
    "error": "Your request has been blocked due to excessive requests. Please reduce rate of requests."
  }
}

{
  "detail": {
    "error": "This request exceeds your plan's set usage limit. Please upgrade your plan or contact [e-mail]"
  }
}

{
  "detail": {
    "error": "This request exceeds the pay-as-you-go limit. You can increase your limit on the Tavily dashboard."
  }
}

{
  "detail": {
    "error": "[500] Internal server error"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header in the form Bearer , where is your Tavily API key (e.g., Bearer tvly-YOUR_API_KEY).

Body

application/json

Parameters for the Tavily Map request.

url · string · required

The root URL to begin the mapping.

Example:

"docs.tavily.com"

instructions · string

Natural language instructions for the crawler. When specified, the cost increases to 2 API credits per 10 successful pages instead of 1 API credit per 10 pages.

Example:

"Find all pages about the Python SDK"

max_depth · integer · default: 1

Max depth of the mapping. Defines how far from the base URL the crawler can explore.

Required range: 1 <= x <= 5

max_breadth · integer · default: 20

Max number of links to follow per level of the tree (i.e., per page).

Required range: 1 <= x <= 500

limit · integer · default: 50

Total number of links the crawler will process before stopping.

Required range: x >= 1

select_paths · string[]

Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*).

select_domains · string[]

Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\.example\.com$).

exclude_paths · string[]

Regex patterns to exclude URLs with specific path patterns (e.g., /private/.*, /admin/.*).

exclude_domains · string[]

Regex patterns to exclude specific domains or subdomains from crawling (e.g., ^private\.example\.com$).

allow_external · boolean · default: true

Whether to include external domain links in the final results list.

timeout · number<float> · default: 150

Maximum time in seconds to wait for the map operation before timing out. Must be between 10 and 150 seconds.

Required range: 10 <= x <= 150

include_usage · boolean · default: false

Whether to include credit usage information in the response.NOTE:The value may be 0 if the total successful pages mapped has not yet reached 10 calls. See our Credits & Pricing documentation for details.

Response

200

application/json

Map results returned successfully

base_url · string

The base URL that was mapped.

Example:

"docs.tavily.com"

results · string[]

A list of URLs that were discovered during the mapping.

Example:

[
  "https://docs.tavily.com/welcome",
  "https://docs.tavily.com/documentation/api-credits",
  "https://docs.tavily.com/documentation/about"
]

response_time · number<float>

Time in seconds it took to complete the request.

Example:

1.23

usage · object

Credit usage details for the request.

Example:

{ "credits": 1 }

request_id · string

A unique request identifier you can share with customer support to help resolve issues with specific requests.

Example:

"123e4567-e89b-12d3-a456-426614174111"