---
title: "Initiate a web mapping from a base URL"
method: POST
path: "/map"
---

# Initiate a web mapping from a base URL

`POST /map`

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

## Request body

- object
  - `url` string, required — The root URL to begin the mapping.
  - `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.
  - `max_depth` integer — Max depth of the mapping. Defines how far from the base URL the crawler can explore.
  - `max_breadth` integer — Max number of links to follow per level of the tree (i.e., per page).
  - `limit` integer — Total number of links the crawler will process before stopping.
  - `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 — Whether to include external domain links in the final results list.
  - `timeout` number, float — Maximum time in seconds to wait for the map operation before timing out. Must be between 10 and 150 seconds.
  - `include_usage` boolean — 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](https://docs.tavily.com/documentation/api-credits) for details.

## Response `200`

Map results returned successfully

- object
  - `base_url` string — The base URL that was mapped.
  - `results` string[] — A list of URLs that were discovered during the mapping.
  - `response_time` number, float — Time in seconds it took to complete the request.
  - `usage` object — Credit usage details for the request.
  - `request_id` string — A unique request identifier you can share with customer support to help resolve issues with specific requests.

## Other responses

- `400` — Bad Request - Your request is invalid.
- `401` — Unauthorized - Your API key is wrong or missing.
- `403` — Forbidden - URL is not supported.
- `429` — Too many requests - Rate limit exceeded
- `432` — Key limit or Plan Limit exceeded
- `433` — PayGo limit exceeded
- `500` — Internal Server Error - We had a problem with our server.

---

[API](https://skmtc.net/tavily/apis/tavily-search-and-extract-api.md) · [All operations](https://skmtc.net/tavily/apis/tavily-search-and-extract-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tavily/tavily-search-and-extract-api/versions/9126e7d2df75/schema)