Sign in

Initiate a web mapping from a base URL

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

Request body

urlstring required

The root URL to begin the mapping.

instructionsstring

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.

max_depthinteger

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

max_breadthinteger

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

limitinteger

Total number of links the crawler will process before stopping.

select_pathsstring[]

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

select_domainsstring[]

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

exclude_pathsstring[]

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

exclude_domainsstring[]

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

allow_externalboolean

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

timeoutnumber float

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

include_usageboolean

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.

Example request

{
  "url": "docs.tavily.com",
  "instructions": "Find all pages about the Python SDK"
}

Response

Map results returned successfully

base_urlstring

The base URL that was mapped.

resultsstring[]

A list of URLs that were discovered during the mapping.

response_timenumber float

Time in seconds it took to complete the request.

usageobject

Credit usage details for the request.

request_idstring

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

Example 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"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.