Tavily Map - Documentation

Tavily Map

curl --request POST \
  --url https://api.novita.ai/v3/tavily/map \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "url": "<string>",
  "instructions": "<string>",
  "max_depth": 123,
  "max_breadth": 123,
  "limit": 123,
  "select_paths": [
    "<string>"
  ],
  "select_domains": [
    "<string>"
  ],
  "exclude_paths": [
    "<string>"
  ],
  "exclude_domains": [
    "<string>"
  ],
  "allow_external": true,
  "timeout": 123
}
'

import requests

url = "https://api.novita.ai/v3/tavily/map"

payload = {
    "url": "<string>",
    "instructions": "<string>",
    "max_depth": 123,
    "max_breadth": 123,
    "limit": 123,
    "select_paths": ["<string>"],
    "select_domains": ["<string>"],
    "exclude_paths": ["<string>"],
    "exclude_domains": ["<string>"],
    "allow_external": True,
    "timeout": 123
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "<authorization>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'},
  body: JSON.stringify({
    url: '<string>',
    instructions: '<string>',
    max_depth: 123,
    max_breadth: 123,
    limit: 123,
    select_paths: ['<string>'],
    select_domains: ['<string>'],
    exclude_paths: ['<string>'],
    exclude_domains: ['<string>'],
    allow_external: true,
    timeout: 123
  })
};

fetch('https://api.novita.ai/v3/tavily/map', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novita.ai/v3/tavily/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' => '<string>',
    'instructions' => '<string>',
    'max_depth' => 123,
    'max_breadth' => 123,
    'limit' => 123,
    'select_paths' => [
        '<string>'
    ],
    'select_domains' => [
        '<string>'
    ],
    'exclude_paths' => [
        '<string>'
    ],
    'exclude_domains' => [
        '<string>'
    ],
    'allow_external' => true,
    'timeout' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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.novita.ai/v3/tavily/map"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_depth\": 123,\n  \"max_breadth\": 123,\n  \"limit\": 123,\n  \"select_paths\": [\n    \"<string>\"\n  ],\n  \"select_domains\": [\n    \"<string>\"\n  ],\n  \"exclude_paths\": [\n    \"<string>\"\n  ],\n  \"exclude_domains\": [\n    \"<string>\"\n  ],\n  \"allow_external\": true,\n  \"timeout\": 123\n}")

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

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "<authorization>")

	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.novita.ai/v3/tavily/map")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "<authorization>")
  .body("{\n  \"url\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_depth\": 123,\n  \"max_breadth\": 123,\n  \"limit\": 123,\n  \"select_paths\": [\n    \"<string>\"\n  ],\n  \"select_domains\": [\n    \"<string>\"\n  ],\n  \"exclude_paths\": [\n    \"<string>\"\n  ],\n  \"exclude_domains\": [\n    \"<string>\"\n  ],\n  \"allow_external\": true,\n  \"timeout\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novita.ai/v3/tavily/map")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = '<authorization>'
request.body = "{\n  \"url\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_depth\": 123,\n  \"max_breadth\": 123,\n  \"limit\": 123,\n  \"select_paths\": [\n    \"<string>\"\n  ],\n  \"select_domains\": [\n    \"<string>\"\n  ],\n  \"exclude_paths\": [\n    \"<string>\"\n  ],\n  \"exclude_domains\": [\n    \"<string>\"\n  ],\n  \"allow_external\": true,\n  \"timeout\": 123\n}"

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

{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "429": {},
  "500": {},
  "502": {},
  "503": {},
  "base_url": "<string>",
  "results": [
    "<string>"
  ],
  "response_time": 123,
  "request_id": "<string>"
}

POST

tavily

map

Tavily Map

curl --request POST \
  --url https://api.novita.ai/v3/tavily/map \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "url": "<string>",
  "instructions": "<string>",
  "max_depth": 123,
  "max_breadth": 123,
  "limit": 123,
  "select_paths": [
    "<string>"
  ],
  "select_domains": [
    "<string>"
  ],
  "exclude_paths": [
    "<string>"
  ],
  "exclude_domains": [
    "<string>"
  ],
  "allow_external": true,
  "timeout": 123
}
'

import requests

url = "https://api.novita.ai/v3/tavily/map"

payload = {
    "url": "<string>",
    "instructions": "<string>",
    "max_depth": 123,
    "max_breadth": 123,
    "limit": 123,
    "select_paths": ["<string>"],
    "select_domains": ["<string>"],
    "exclude_paths": ["<string>"],
    "exclude_domains": ["<string>"],
    "allow_external": True,
    "timeout": 123
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "<authorization>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'},
  body: JSON.stringify({
    url: '<string>',
    instructions: '<string>',
    max_depth: 123,
    max_breadth: 123,
    limit: 123,
    select_paths: ['<string>'],
    select_domains: ['<string>'],
    exclude_paths: ['<string>'],
    exclude_domains: ['<string>'],
    allow_external: true,
    timeout: 123
  })
};

fetch('https://api.novita.ai/v3/tavily/map', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novita.ai/v3/tavily/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' => '<string>',
    'instructions' => '<string>',
    'max_depth' => 123,
    'max_breadth' => 123,
    'limit' => 123,
    'select_paths' => [
        '<string>'
    ],
    'select_domains' => [
        '<string>'
    ],
    'exclude_paths' => [
        '<string>'
    ],
    'exclude_domains' => [
        '<string>'
    ],
    'allow_external' => true,
    'timeout' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$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.novita.ai/v3/tavily/map"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_depth\": 123,\n  \"max_breadth\": 123,\n  \"limit\": 123,\n  \"select_paths\": [\n    \"<string>\"\n  ],\n  \"select_domains\": [\n    \"<string>\"\n  ],\n  \"exclude_paths\": [\n    \"<string>\"\n  ],\n  \"exclude_domains\": [\n    \"<string>\"\n  ],\n  \"allow_external\": true,\n  \"timeout\": 123\n}")

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

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "<authorization>")

	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.novita.ai/v3/tavily/map")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "<authorization>")
  .body("{\n  \"url\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_depth\": 123,\n  \"max_breadth\": 123,\n  \"limit\": 123,\n  \"select_paths\": [\n    \"<string>\"\n  ],\n  \"select_domains\": [\n    \"<string>\"\n  ],\n  \"exclude_paths\": [\n    \"<string>\"\n  ],\n  \"exclude_domains\": [\n    \"<string>\"\n  ],\n  \"allow_external\": true,\n  \"timeout\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novita.ai/v3/tavily/map")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = '<authorization>'
request.body = "{\n  \"url\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_depth\": 123,\n  \"max_breadth\": 123,\n  \"limit\": 123,\n  \"select_paths\": [\n    \"<string>\"\n  ],\n  \"select_domains\": [\n    \"<string>\"\n  ],\n  \"exclude_paths\": [\n    \"<string>\"\n  ],\n  \"exclude_domains\": [\n    \"<string>\"\n  ],\n  \"allow_external\": true,\n  \"timeout\": 123\n}"

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

{
  "400": {},
  "401": {},
  "403": {},
  "404": {},
  "429": {},
  "500": {},
  "502": {},
  "503": {},
  "base_url": "<string>",
  "results": [
    "<string>"
  ],
  "response_time": 123,
  "request_id": "<string>"
}

Tavily is a web data retrieval API designed for developers and AI applications. This document describes the Tavily passthrough endpoints exposed by the platform gateway. It is based on Tavily’s Map API with platform route prefixes applied. Base URL example: https://api.novita.ai Map a site starting from a root URL, following links to discover the structure of reachable pages and return their URLs.

Request Headers

All endpoints require platform API authentication.

Content-Type

string

required

Use application/json.

Authorization

string

required

Platform API key, formatted as Bearer <api_key>.

Request Body

url

string

required

Crawl root URL.

instructions

string

Crawler instructions in natural language.

max_depth

integer

Crawler depth limit. Default is 1; range is 1 to 5.

max_breadth

integer

Max links per page. Default is 20; range is 1 to 500.

limit

integer

Link processing limit for crawler. Default is 50; minimum is 1.

select_paths

string[]

Restrict URL paths matching these regex patterns.

select_domains

string[]

Restrict domains matching these regex patterns.

exclude_paths

string[]

Exclude URL paths matching these regex patterns.

exclude_domains

string[]

Exclude domains matching these regex patterns.

allow_external

boolean

Include external domain links.

timeout

float

Crawl operation time limit in seconds. Default is 150; range is 10 to 150.

Request Example

curl -s -X POST 'https://api.novita.ai/v3/tavily/map' \
  -H 'Authorization: Bearer sk-123' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 2,
    "max_breadth": 20,
    "limit": 50,
    "select_paths": ["/docs/.*"],
    "exclude_paths": ["/admin/.*"],
    "allow_external": false,
    "timeout": 60
  }'

Response

base_url

string

Crawl base URL.

results

string[]

URLs discovered during mapping.

response_time

float

Request duration in seconds.

request_id

string

Unique request identifier.

Errors

The platform may return standard HTTP errors before forwarding the request, and Tavily may return upstream errors after forwarding.

400

status

Invalid request body or unsupported parameter value.

401

status

Missing or invalid API key.

403

status

Access denied by platform or upstream provider, or the URL is not supported.

404

status

Route or requested resource not found.

429

status

Rate limit exceeded.

500

status

Internal server error.

502

status

Upstream provider error.

503

status

Service unavailable.

Notes

All request bodies are JSON.
Extra Tavily parameters not listed here may be passed through.
Response shapes can vary depending on request options.
This document intentionally omits billing-related fields.

References

For more details, see the Tavily Map API reference.

Last modified on June 23, 2026

Tavily Extract Tavily Crawl

⌘I

​Request Headers

​Request Body

​Request Example

​Response

​Errors

​Notes

​References

Request Headers

Request Body

Request Example

Response

Errors

Notes

References