Skip to content
looot docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Tavily Search and Extract API / Initiate a web mapping from a base URL

Tavily Search and Extract API tool tavily-map on looot: input fields, $0.0008 per result, output shape, and code to run it with curl, JavaScript or Python.

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

Inputs

Name Type Required Description
allow_external boolean no Whether to include external domain links in the final results list.
exclude_domains array no Regex patterns to exclude specific domains or subdomains from crawling (e.g., ^private\.example\.com$).
exclude_paths array no Regex patterns to exclude URLs with specific path patterns (e.g., /private/.*, /admin/.*).
include_usage boolean no 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.
instructions string no 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”
limit integer no Total number of links the crawler will process before stopping.
max_breadth integer no Max number of links to follow per level of the tree (i.e., per page).
max_depth integer no Max depth of the mapping. Defines how far from the base URL the crawler can explore.
select_domains array no Regex patterns to select crawling to specific domains or subdomains (e.g., ^docs\.example\.com$).
select_paths array no Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*).
timeout number no Maximum time in seconds to wait for the map operation before timing out. Must be between 10 and 150 seconds.
url string yes The root URL to begin the mapping. Example: “docs.tavily.com”

Output

Shape of the run’s result, checked against 1 real answer:

{ results: unknown[], base_url, request_id, response_time }

Run it

Every call needs your API token in LOOOT_TOKEN; Sign in shows how to get one. Each run also needs a new idempotency key, so a retry never pays twice. With wait: 30 the answer comes back inline when the run ends within 30 seconds. Otherwise you get the running run back: poll GET /v1/runs/<runId>.

Example input with placeholder values:

curl -X POST "https://api.looot.ai/v1/runs" \
  -H "Authorization: Bearer $LOOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"endpointId":"tavily-map","input":{"url":"docs.tavily.com","instructions":"Find all pages about the Python SDK"},"wait":30}'
const response = await fetch("https://api.looot.ai/v1/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOOT_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    endpointId: "tavily-map",
    input: {
      url: "docs.tavily.com",
      instructions: "Find all pages about the Python SDK",
    },
    wait: 30,
  }),
});
const run = await response.json();
console.log(run.status, run.result);
import os
import uuid

import requests

response = requests.post(
    "https://api.looot.ai/v1/runs",
    headers={
        "Authorization": f"Bearer {os.environ['LOOOT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "endpointId": "tavily-map",
        "input": {
            "url": "docs.tavily.com",
            "instructions": "Find all pages about the Python SDK",
        },
        "wait": 30,
    },
    timeout=90,
)
run = response.json()
print(run["status"], run.get("result"))

To let looot pick among every provider of this job instead, send job:web.site.map as endpointId; see the job page.

Was this page helpful?