# 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?