Skip to main content
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,
  "usage": {
    "credits": 1
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174111"
}

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: 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.

​
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

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"