# Tavily Map API (https://www.socialcrawl.dev/platforms/tavily/map)

> Returns the sitegraph of a website starting from a root URL — a list of discovered URLs without their full content. Cheaper and faster than crawl when you only need to enumerate pages (e.g. for sitemap discovery or coverage analysis). Use `instructions` to guide the mapper in natural language and the `select_*` / `exclude_*` filters (regex patterns, comma-separated) to narrow scope.

TL;DR: `GET /v1/tavily/map` costs 1 credit per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Root URL to begin mapping. |
| `max_depth` | no | Maximum link depth from the root URL. Defaults to 1. |
| `max_breadth` | no | Maximum number of links followed per level (per page). Defaults to 20. |
| `limit` | no | Total number of links the mapper will process before stopping. Defaults to 50. |
| `instructions` | no | Natural-language instructions for the mapper (e.g. 'Find all pages related to API documentation'). |
| `select_paths` | no | Comma-separated regex patterns — only include URLs whose path matches. |
| `select_domains` | no | Comma-separated regex patterns — only include URLs whose domain matches. |
| `exclude_paths` | no | Comma-separated regex patterns — exclude URLs whose path matches. |
| `exclude_domains` | no | Comma-separated regex patterns — exclude URLs whose domain matches. |
| `allow_external` | no | Whether to follow / return links to external domains. Defaults to true. |
| `timeout` | no | Maximum time in seconds (10–150). |
| `categories` | no | Comma-separated list of category hints to bias mapping toward. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/tavily/map?url=https%3A%2F%2Fdocs.tavily.com" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I map a website's structure with the Tavily API?

Send a GET request to /v1/tavily/map with the site's root in the url parameter and your SocialCrawl x-api-key. Tavily traverses links from that root and returns the discovered URLs as a sitegraph — a fast way to learn a site's layout without fetching every page's content.

### What controls how deep and wide the map goes?

max_depth sets how many link hops out from the root, max_breadth caps links followed per level, and limit caps the total URLs returned. Tune these to balance coverage against credit and time for large sites.

### Can I restrict the map to certain sections of a site?

Yes. Use path filters to include or exclude URL paths (e.g. only /docs) and domain filters to keep the map on the target domain or allow specific subdomains. This keeps the sitegraph focused on the section you care about.

### How is map different from crawl?

Map discovers URLs and returns the link structure without extracting page content, so it is fast and cheap for understanding a site's shape. Crawl walks the site and pulls content along the way. Use map to plan, then crawl or extract to ingest.

### How much does the Tavily Map API cost?

Each map call costs 1 credit on the standard tier. New accounts get 100 free credits with no credit card required — enough to map many sites and tune depth, breadth, and limit before you pay anything.

See the full Tavily API: https://www.socialcrawl.dev/platforms/tavily

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to build a website sitemap graph with the Tavily API on SocialCrawl
- What is the difference between Tavily map and crawl?