POST
/
map
Python SDK
from tavily import TavilyClient

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

print(response)
{
  "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,
  "request_id": "123e4567-e89b-12d3-a456-426614174111"
}
Beta Feature - The Tavily Map endpoint is currently in Beta. While fully functional, the API may undergo changes as we continue to refine and improve the service.

Authorizations

​
Authorization
string
header
required

Bearer authentication header in the form Bearer <token>, where <token> 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: x >= 1
​
max_breadth
integer
default:20

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

Required range: x >= 1
​
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.

Response

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

Time in seconds it took to complete the request.

Example:

1.23

​
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"