Tavily

View saved version →

---
name: tavily-best-practices
description: "Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, etc.) to implement web search, content extraction, crawling, and research in agentic workflows, RAG systems, or autonomous agents."
---

# Tavily

Tavily is a search API designed for LLMs, enabling AI applications to access real-time web data.

## Installation

**Python:**
```bash
pip install tavily-python
```

**JavaScript:**
```bash
npm install @tavily/core
```

See **[references/sdk.md](references/sdk.md)** for complete SDK reference.

## Client Initialization

```python
from tavily import TavilyClient

# Uses TAVILY_API_KEY env var (recommended)
client = TavilyClient()

#With project tracking (for usage organization)
client = TavilyClient(project_id="your-project-id")

# Async client for parallel queries
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()
```

## Choosing the Right Method

**For custom agents/workflows:**

| Need | Method |
|------|--------|
| Web search results | `search()` |
| Content from specific URLs | `extract()` |
| Content from entire site | `crawl()` |
| URL discovery from site | `map()` |

**For out-of-the-box research:**

| Need | Method |
|------|--------|
| End-to-end research with AI synthesis | `research()` |

## Quick Reference

### search() - Web Search

```python
response = client.search(
    query="quantum computing breakthroughs",  # Keep under 400 chars
    max_results=10,
    search_depth="advanced"
)
print(response)
```
Key parameters: `query`, `max_results`, `search_depth` (ultra-fast/fast/basic/advanced), `include_domains`, `exclude_domains`, `time_range`

See **[references/search.md](references/search.md)** for complete search reference.

### extract() - URL Content Extraction

```python
# Simple one-step extraction
response = client.extract(
    urls=["https://docs.example.com"],
    extract_depth="advanced"
)
print(response)
```
Key parameters: `urls` (max 20), `extract_depth`, `query`, `chunks_per_source` (1-5)

See **[references/extract.md](references/extract.md)** for complete extract reference.

### crawl() - Site-Wide Extraction

```python
response = client.crawl(
    url="https://docs.example.com",
    instructions="Find API documentation pages",  # Semantic focus
    extract_depth="advanced"
)
print(response)
```
Key parameters: `url`, `max_depth`, `max_breadth`, `limit`, `instructions`, `chunks_per_source`, `select_paths`, `exclude_paths`

See **[references/crawl.md](references/crawl.md)** for complete crawl reference.

### map() - URL Discovery

```python
response = client.map(
    url="https://docs.example.com"
)
print(response)
```

### research() - AI-Powered Research

```python
import time

# For comprehensive multi-topic research
result = client.research(
    input="Analyze competitive landscape for X in SMB market",
    model="pro"  # or "mini" for focused queries, "auto" when unsure
)
request_id = result["request_id"]

# Poll until completed
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
    time.sleep(10)
    response = client.get_research(request_id)

print(response["content"])  # The research report
```

Key parameters: `input`, `model` ("mini"/"pro"/"auto"), `stream`, `output_schema`, `citation_format`

See **[references/research.md](references/research.md)** for complete research reference.

## Detailed Guides

For complete parameters, response fields, patterns, and examples:

- **[references/sdk.md](references/sdk.md)** - Python & JavaScript SDK reference, async patterns, Hybrid RAG
- **[references/search.md](references/search.md)** - Query optimization, search depth selection, domain filtering, async patterns, post-filtering
- **[references/extract.md](references/extract.md)** - One-step vs two-step extraction, query/chunks for targeting, advanced mode
- **[references/crawl.md](refere

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: tavily-crawl
description: |
  Crawl websites and extract content from multiple pages via the Tavily CLI. Use this skill when the user wants to crawl a site, download documentation, extract an entire docs section, bulk-extract pages, save a site as local markdown files, or says "crawl", "get all the pages", "download the docs", "extract everything under /docs", "bulk extract", or needs content from many pages on the same domain. Supports depth/breadth control, path filtering, semantic instructions, and saving each page as a local markdown file.
allowed-tools: Bash(tvly *)
---

# tavily crawl

Crawl a website and extract content from multiple pages. Supports saving each page as a local markdown file.

## Before running

Crawl requires authentication. Run the requested command directly when `tvly`
is already authenticated; do not add a status check to every invocation.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup).
If an installed CLI reports an authentication error, use `tvly login` for
authentication only, or `tvly init --skip-skills` when guided verification is
also useful. Browser-based OAuth is preferred when an interactive user can
complete it. `--no-browser` prints the sign-in link instead of opening it, but
still waits for a localhost callback. In an unattended agent or CI environment,
leave authentication to the user or use a securely provided `TAVILY_API_KEY`.
Do not start a second login immediately after guided setup has completed.

## When to use

- You need content from many pages on a site (e.g., all `/docs/`)
- You want to download documentation for offline use
- Step 4 in the [workflow](../tavily-cli/SKILL.md): search → extract → map → **crawl** → research

## Quick start

```bash
# Basic crawl
tvly crawl "https://docs.example.com" --json

# Save each page as a markdown file
tvly crawl "https://docs.example.com" --output-dir ./docs/

# Deeper crawl with limits
tvly crawl "https://docs.example.com" --max-depth 2 --limit 50 --json

# Filter to specific paths
tvly crawl "https://example.com" --select-paths "/api/.*,/guides/.*" --exclude-paths "/blog/.*" --json

# Semantic focus (returns relevant chunks, not full pages)
tvly crawl "https://docs.example.com" --instructions "Find authentication docs" --chunks-per-source 3 --json
```

## Options

| Option | Description |
|--------|-------------|
| `--max-depth` | Levels deep (1-5, default: 1) |
| `--max-breadth` | Links per page (default: 20) |
| `--limit` | Total pages cap (default: 50) |
| `--instructions` | Natural language guidance for semantic focus |
| `--chunks-per-source` | Chunks per page (1-5, requires `--instructions`) |
| `--extract-depth` | `basic` (default) or `advanced` |
| `--format` | `markdown` (default) or `text` |
| `--select-paths` | Comma-separated regex patterns to include |
| `--exclude-paths` | Comma-separated regex patterns to exclude |
| `--select-domains` | Comma-separated regex for domains to include |
| `--exclude-domains` | Comma-separated regex for domains to exclude |
| `--allow-external / --no-external` | Include external links (default: allow) |
| `--include-images` | Include images |
| `--timeout` | Max wait (10-150 seconds) |
| `-o, --output` | Save JSON output to file |
| `--output-dir` | Save each page as a .md file in directory |
| `--json` | Structured JSON output |

## Crawl for context vs. data collection

**For agentic use** (feeding results to an LLM):

Always use `--instructions` + `--chunks-per-source`. Returns only relevant chunks instead of full pages — prevents context explosion.

```bash
tvly crawl "https://docs.example.com" --instructions "API authentication" --chunks-per-source 3 --json
```

**For data collection** (saving to files):

Use `--output-dir` without `--chunks-per-source` to get full pages as markdown files.

```bash
tvly crawl "https://docs.example.com" --max-depth 2 --output-dir ./docs/
```

## Tips

- **Start conservative** — `--max-depth 1`, `--limit 20` — a

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: tavily-entity
description: |
  Fill in a company, person, or organization for a CRM from the web, using Tavily, including a CSV of rows the user already has. Identifies the right entity when others share the name, then fills the fields from authoritative sources. Use when the user wants to enrich an account, a spreadsheet, or a pasted list of known names, or says "enrich", "CRM", or "who is". For discovering matches use tavily-list. For a deep comprehensive report use tavily-research.
allowed-tools: Bash(tvly *)
---

# Tavily entity

Resolve one entity and return a CRM record. The name is not the identity.
Confirm which entity it is, then fill the record from authoritative sources.
Every value comes from a page you read. An empty field stays empty.

Search and extract as `tavily-search` describes; load it only if it isn't
loaded yet. To discover new matches use `tavily-list`; for a deep report use
`tavily-research`.

## Identify the entity first

People and companies share names. A record that mixes two of them is worse
than an empty one. Isolate a single entity before you fill any field.

1. Take the type (company, person, or organization) and every identifier the
   user already gave: a domain, a city, an employer, a title, a product.
2. Search the name and look for other entities that use it. A common name, a
   name that is also a product or a place, or a person with a common name is a
   collision until you prove otherwise.
3. You have the right entity only when two identifiers agree. For a company,
   the name plus its own domain. For a person, the name plus an employer, a
   location, or a profile they control, and the organization on that profile
   has to match. One page that mentions the name is not identification.
4. If more than one entity still fits, stop and return the candidates. Do not
   pick the one with more results, and do not copy a field from one candidate
   onto another.
5. Put a stable identifier, the domain or the employer, into every later
   search, not the bare name.

## Read authoritative sources

Fill a field from the page that owns the fact. Extract that page. A snippet is
not enough for a number.

- The entity's own site, an official profile, and a filing or registry come
  first for facts the entity publishes: what it is, where it is, who leads it,
  what it sells. For a person, the employer's team page or a profile the person
  controls comes before a people-search site.
- A directory, a data broker, or a roundup is a lead to that page. Use it as
  the source of a field only when no authoritative page states the fact, and
  say so in the source note.
- When two authoritative pages disagree on a number, keep the more direct one
  and record the other in the source note. Do not average them.
- Include a published email or phone number only when a page shows it.

Extract the pages that own the fields you need in one call. Search for recent
news, with the domain or employer in the query, only when the user wants recent
signals or a full record.

## A CSV of known rows

When the user already has the entities, in a file or a pasted table, enrich
those rows. Do not go looking for new names.

1. Read the rows and count them. Use the fields they named. If they did not
   name fields, ask once, then use the same fields on every row.
2. Above 25 rows, tell them the count and the fields and wait for a go-ahead.
3. For each row, follow Identify the entity first and Read authoritative
   sources. A row you cannot isolate stays unresolved: blank new fields, a note
   on what collided, and no guessed values.
4. Write the original columns plus the new fields, a source for each new
   field, and a status of `filled` or `unresolved` to
   `{name}-enriched-{YYYY-MM-DD}.csv`. Use a CSV writer.

The CSV is the result. In the reply, give the number filled, the number
unresolved, and the path. Do not paste a record per row.

## Output

When the user asked specific questions, answer those in the reply, with

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: tavily-extract
description: |
  Extract clean markdown or text content from specific URLs via the Tavily CLI. Use this skill when the user has one or more URLs and wants their content, says "extract", "grab the content from", "pull the text from", "get the page at", "read this webpage", or needs clean text from web pages. Handles JavaScript-rendered pages, returns LLM-optimized markdown, and supports query-focused chunking for targeted extraction. Can process up to 20 URLs in a single call.
allowed-tools: Bash(tvly *)
---

# tavily extract

Extract clean markdown or text content from one or more URLs.

## Before running

Run extract directly when `tvly` is available. Extract supports capped keyless
access, so do not look for an API key or authenticate before the first request.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup)
before retrying. If the keyless cap is reached in an interactive session, run
`tvly login` to open browser OAuth, then retry the original extraction once. In
an unattended environment, report the cap and authentication options instead
of starting an interactive flow. Do not start a second login immediately after
guided setup has completed.

## When to use

- You have a specific URL and want its content
- You need text from JavaScript-rendered pages
- Step 2 in the [workflow](../tavily-cli/SKILL.md): search → **extract** → map → crawl → research

## Quick start

```bash
# Single URL
tvly extract "https://example.com/article" --json

# Multiple URLs
tvly extract "https://example.com/page1" "https://example.com/page2" --json

# Query-focused extraction (returns relevant chunks only)
tvly extract "https://example.com/docs" --query "authentication API" --chunks-per-source 3 --json

# JS-heavy pages
tvly extract "https://app.example.com" --extract-depth advanced --json

# Save to file
tvly extract "https://example.com/article" -o article.json
```

## Options

| Option | Description |
|--------|-------------|
| `--query` | Rerank chunks by relevance to this query |
| `--chunks-per-source` | Chunks per URL (1-5, requires `--query`) |
| `--extract-depth` | `basic` (default) or `advanced` (for JS pages) |
| `--format` | `markdown` (default) or `text` |
| `--include-images` | Include image URLs |
| `--timeout` | Max wait time (1-60 seconds) |
| `-o, --output` | Save the JSON response to a file |
| `--json` | Structured JSON output |

## Extract depth

| Depth | When to use |
|-------|-------------|
| `basic` | Simple pages, fast — try this first |
| `advanced` | JS-rendered SPAs, dynamic content, tables |

## Tips

- **Max 20 URLs per request** — batch larger lists into multiple calls.
- **Use `--query` + `--chunks-per-source`** to get only relevant content instead of full pages.
- **Try `basic` first**, fall back to `advanced` if content is missing.
- **Set `--timeout`** for slow pages (up to 60s).
- **Inspect `failed_results` even after exit code 0.** A successful request can
  still return no extracted pages. Retry the affected URL with `advanced` when
  appropriate, otherwise report the per-URL failure instead of treating the
  request as complete.
- If search results already contain the content you need (via `--include-raw-content`), skip the extract step.

## See also

- [tavily-search](../tavily-search/SKILL.md) — find pages when you don't have a URL
- [tavily-crawl](../tavily-crawl/SKILL.md) — extract content from many pages on a site

View saved version →

---
name: tavily-list
description: |
  Build a deduplicated table of matches for a set, using Tavily. The table is what search returned, not every match that exists. Use when the user wants a list, all of something, or a table with duplicates removed. Confirm the columns and a cap before searching. For one CRM record, or a CSV of rows they already have, use tavily-entity. For a deep comprehensive report use tavily-research.
allowed-tools: Bash(tvly *)
---

# Tavily list

Return the matches you can verify for a set, one row each, with duplicates
merged. The table is the result. It is not every match that exists. Do not
collapse rows into a summary, and do not call the table complete.

Use `tavily-search` to search and read pages. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-search` and read its SKILL.md before continuing. When you open many list pages, save the responses and filter them the way that skill describes, so the raw pages stay out of context.

## When this is the wrong skill

- The user wants one record filled in, or fields added to a CSV of rows they already have. Use `tavily-entity`. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-entity` and read its SKILL.md before continuing.
- The user wants a deep comprehensive report. Use `tavily-research`. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-research` and read its SKILL.md before continuing.

## Steps

1. Before any search, fix the inclusion rule in one sentence, the columns, and
   a cap. Columns always include name, website or profile, a one-line
   description, and the source URL, plus any the user named. If they did not
   name the extra columns or a cap, ask once and wait. If the set is unbounded
   ("every restaurant"), that question includes the boundary, such as a city
   or a category. A row gets in only when it matches the inclusion rule.
2. Search the set from several angles: the category, "list of" roundups,
   directories, and the names that appear on pages you have already opened. One
   query does not cover the set. Pull every name off a page that is itself a
   list.
3. Give each row an identity. For an organization, that is the website host
   with `www` removed. For a person, it is the profile URL, or the name plus
   the organization when there is no profile. For a product on a shared host,
   it is the canonical URL.
4. Merge rows that share an identity. Keep the fuller row and record the names
   you folded in. When a match has no website yet, search for it once before
   you finish. If it still has none, keep the row and leave the website blank.
5. Stop at the cap, or when two new angles in a row add no rows. Say which.
   Either stop means this pass is finished. Neither means the set is complete.
6. When the user wants more, search again and exclude every name and website
   already in the table. Append only new rows, then merge by identity again.
   Raise the cap by the number they asked for.

Use the same columns on every row. Leave a cell blank when no page states it.

Use `tavily-entity` for a row only when the user asked for CRM fields on each match. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-entity` and read its SKILL.md before continuing. Otherwise a list row stays a list row.

## Output

Show the table in the reply, and save the same markdown to `lists/{title}.md`
in the working directory. The title is sentence case, 3 to 6 words, letters,
numbers, and single spaces.

```markdown
# {Title}

Inclusion: {one sentence}
As of: {YYYY-MM-DD}
Cap: {N}
Stop: {two angles added nothing | hit the cap}
Rows: {count after dedup}
Coverage: not exhaustive. This is what the angles below returned.

| Name | Website | Description | {asked columns} | Source |
|---|---|---|---|---|

## Merged
- {kept name} ← {other names} ({shared website})

## Coverage
Angles: {the queries and the list pages you opened}
Excluded this pass: {names and web

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: tavily-map
description: |
  Discover and list all URLs on a website without extracting content, via the Tavily CLI. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where something is on a domain, or says "map the site", "find the URL for", "what pages are on", "list all pages", or "site structure". Faster than crawling — returns URLs only. Essential when you know the site but not the exact page. Combine with extract for targeted content retrieval.
allowed-tools: Bash(tvly *)
---

# tavily map

Discover URLs on a website without extracting content. Faster than crawling.

## Before running

Map requires authentication. Run the requested command directly when `tvly`
is already authenticated; do not add a status check to every invocation.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup).
If an installed CLI reports an authentication error, use `tvly login` for
authentication only, or `tvly init --skip-skills` when guided verification is
also useful. Browser-based OAuth is preferred when an interactive user can
complete it. `--no-browser` prints the sign-in link instead of opening it, but
still waits for a localhost callback. In an unattended agent or CI environment,
leave authentication to the user or use a securely provided `TAVILY_API_KEY`.
Do not start a second login immediately after guided setup has completed.

## When to use

- You need to find a specific subpage on a large site
- You want a list of all URLs before deciding what to extract or crawl
- Step 3 in the [workflow](../tavily-cli/SKILL.md): search → extract → **map** → crawl → research

## Quick start

```bash
# Discover all URLs
tvly map "https://docs.example.com" --json

# With natural language filtering
tvly map "https://docs.example.com" --instructions "Find API docs and guides" --json

# Filter by path
tvly map "https://example.com" --select-paths "/blog/.*" --limit 500 --json

# Deep map
tvly map "https://example.com" --max-depth 3 --limit 200 --json
```

## Options

| Option | Description |
|--------|-------------|
| `--max-depth` | Levels deep (1-5, default: 1) |
| `--max-breadth` | Links per page (default: 20) |
| `--limit` | Max URLs to discover (default: 50) |
| `--instructions` | Natural language guidance for URL filtering |
| `--select-paths` | Comma-separated regex patterns to include |
| `--exclude-paths` | Comma-separated regex patterns to exclude |
| `--select-domains` | Comma-separated regex for domains to include |
| `--exclude-domains` | Comma-separated regex for domains to exclude |
| `--allow-external / --no-external` | Include external links |
| `--timeout` | Max wait (10-150 seconds) |
| `-o, --output` | Save the JSON response to a file |
| `--json` | Structured JSON output |

## Map + Extract pattern

Use `map` to find the right page, then `extract` it. This is often more efficient than crawling an entire site:

```bash
# Step 1: Find the authentication docs
tvly map "https://docs.example.com" --instructions "authentication" --json

# Step 2: Extract the specific page you found
tvly extract "https://docs.example.com/api/authentication" --json
```

## Tips

- **Map is URL discovery only** — no content extraction. Use `extract` or `crawl` for content.
- **Map + extract beats crawl** when you only need a few specific pages from a large site.
- **Use `--instructions`** for semantic filtering when path patterns aren't enough.

## See also

- [tavily-extract](../tavily-extract/SKILL.md) — extract content from URLs you discover
- [tavily-crawl](../tavily-crawl/SKILL.md) — bulk extract when you need many pages

View saved version →

---
name: tavily-monitor
description: |
  Build a Tavily search or extraction that runs on a cadence, with a saved baseline. Search monitors set max_age_hours to the interval so a cached copy from before it is not returned. Use when the user wants to monitor, track, watch, or be alerted when something changes, or asks for a recurring check of a query or a page. For a deep comprehensive report use tavily-research. For a one-time lookup use tavily-search. For a one-time table use tavily-list.
allowed-tools: Bash(tvly *)
---

# Tavily monitor

Turn a watch into a search or an extraction that can run again unchanged, then
run it once and save the baseline. The monitor file is the result.

Use `tavily-search` to run the check. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-search` and read its SKILL.md before continuing.

## When this is the wrong skill

- The user wants a deep comprehensive report. Use `tavily-research`. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-research` and read its SKILL.md before continuing.
- The user wants every current match, once. Use `tavily-list`. If it isn't installed, run `npx skills add tavily-ai/skills --skill tavily-list` and read its SKILL.md before continuing.

## Pick the kind

| You have | Kind | What "changed" means |
|---|---|---|
| A topic, and the pages are not known yet | search | A result URL that was not in the previous snapshot |
| One or more known URLs | extract | The hash of that page's extracted content changed |

Use search for mentions, news, jobs, and anything where new pages appear. Use
extract for a pricing page, a changelog, a docs page, or a status page.

## Steps

1. Write the query or the URL list so the next run can reuse it verbatim. Follow
   `tavily-search` for how to shape it. Leave dates and "latest" out of the
   query. The snapshot, not the wording, decides what is new.
2. Write the change rule in one sentence. For a search, a new URL is the
   alert. A URL from the last snapshot that is missing this run is not an
   alert: a page that could not be fetched live is left out. For an extract, a
   changed hash is the alert, and the alert quotes the part the user cares
   about (the price, the version), not the whole page.
3. Name a cadence. Use the one the user asked for. If they did not, use daily
   for news and changelogs, and weekly for a page that changes slowly, and say
   which you chose. On a search, set `max_age_hours` to that interval in hours,
   so a cached copy older than the cadence is not returned. Daily is 24, weekly
   is 168. Use `0` when the interval is under an hour, and `720` when it is
   longer than 30 days. Read how the parameter works in the search reference of
   `tavily-search`. Write the number in the monitor file and send it on every
   run, including the first. Extract does not take `max_age_hours`.
4. Run it once. If the results are the wrong kind of thing, fix the query or
   the URLs and run again before you save anything. If the search is refused
   with `434`, the run did not complete. Say so, and leave `snapshot.json` as
   it was.
5. Save the monitor and the snapshot. The next run reads the monitor, runs the
   same search or extract, reports only what the change rule flags, and
   replaces `snapshot.json`.

Create `monitors/{name}/` in the working directory. The name is sentence case,
3 to 6 words, letters, numbers, and single spaces. Quote it in shell commands.

Do not start a scheduler unless the user asks for one. When they do, and the
environment has a way to run on that cadence, point it at this folder.

A later change to the query or the URL list is a new monitor. It gets a new
folder and a new baseline. Editing them in place makes the next diff meaningless.

## Output

`monitors/{name}/monitor.md`:

```markdown
# {Name}

- Cadence: {daily | weekly on Monday | the schedule the user asked for}
- Kind: search | extract
- Query: {the query, for a search}
- URLs: {one pe

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: tavily-research
description: |
  Research a topic in depth with Tavily. Use this skill when a question needs many sources gathered and weighed together: analysing a market, policy, technology or trend, comparing options across several criteria, reviewing the literature, or any request to research, investigate or analyze something in depth. A single fact or answer to find, even one with many clues, is a tavily-search task. For one CRM record use tavily-entity, for a table of matches use tavily-list, and for a recurring check use tavily-monitor.
allowed-tools: Bash(tvly *)
---

# Tavily research

Use this when the answer has to be built from many sources. A single fact or
answer to find is a search: follow `tavily-search` instead.

Search and read pages as `tavily-search` describes. Load it only if it isn't
loaded yet.

## Steps

### 1. Ask only when the answer would change the research

Ask when a term has two meanings, the user assumed a place, or a name is two
different entities. Otherwise start.

### 2. Split the question

Split into subtopics that do not overlap and that together cover the question.
Carry the user's limits with every subtopic: dates, places, and what is out of
scope. Use 3 subtopics when you are unsure, 4 for a comparison with separate
criteria, 5 for separate entities, regions or domains, and more only for a
large set.

### 3. Research the subtopics together

**With subagents:** choose a title of 3 to 6 words, create
`research_notes/{title}/` and `reports/` in the working directory, and start
one general-purpose subagent per subtopic in the same turn. Give each the
subtopic, the key questions, the user's limits, the absolute path of its notes
file, and this first step: read `references/researcher.md` at its absolute path
next to this skill.

**On your own:** run each subtopic's searches in parallel, as `tavily-search`
describes, and extract the main sources for each. Keep the findings and their
URLs in your context. Don't write notes files.

### 4. Fill thin parts, then write

Before writing, run another round for any part of the question that would
leave its section thin.

### 5. Write and deliver the answer

Follow `references/report-writer.md`. On your own, write it once, as
your reply. Save it to `reports/{title}.md` only when the user asked for a
file, and then give the path after the report. With subagents, have one agent
write `reports/{title}.md` from the notes, then give the user the full report
in your reply, followed by its path.

If this conversation already produced a report on the subject, build on it:
research only what is new or needs checking again.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: tavily-sdk
description: "Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants to implement web search, content extraction, crawling, and research in agentic workflows, RAG systems, or autonomous agents."
---

# Tavily

Tavily is a search API designed for LLMs, enabling AI applications to access real-time web data.

## Installation

**Python:**
```bash
pip install tavily-python
```

**JavaScript:**
```bash
npm install @tavily/core
```

See **[references/sdk.md](references/sdk.md)** for complete SDK reference.

## Client Initialization

```python
from tavily import TavilyClient

# Uses TAVILY_API_KEY env var (recommended)
client = TavilyClient()

#With project tracking (for usage organization)
client = TavilyClient(project_id="your-project-id")

# Async client for parallel queries
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()
```

## Choosing the Right Method

**For custom agents/workflows:**

| Need | Method |
|------|--------|
| Web search results | `search()` |
| Content from specific URLs | `extract()` |
| Content from entire site | `crawl()` |
| URL discovery from site | `map()` |

**For out-of-the-box research:**

| Need | Method |
|------|--------|
| End-to-end research with AI synthesis | `research()` |

## Quick Reference

### search() - Web Search

```python
response = client.search(
    query="quantum computing breakthroughs",  # Keep under 400 chars
    max_results=10,
    search_depth="advanced"
)
print(response)
```
Key parameters: `query`, `max_results`, `search_depth` (ultra-fast/fast/basic/advanced), `include_domains`, `exclude_domains`, `time_range`

See **[references/search.md](references/search.md)** for complete search reference.

### extract() - URL Content Extraction

```python
# Simple one-step extraction
response = client.extract(
    urls=["https://docs.example.com"],
    extract_depth="advanced"
)
print(response)
```
Key parameters: `urls` (max 20), `extract_depth`, `query`, `chunks_per_source` (1-5)

See **[references/extract.md](references/extract.md)** for complete extract reference.

### crawl() - Site-Wide Extraction

```python
response = client.crawl(
    url="https://docs.example.com",
    instructions="Find API documentation pages",  # Semantic focus
    extract_depth="advanced"
)
print(response)
```
Key parameters: `url`, `max_depth`, `max_breadth`, `limit`, `instructions`, `chunks_per_source`, `select_paths`, `exclude_paths`

See **[references/crawl.md](references/crawl.md)** for complete crawl reference.

### map() - URL Discovery

```python
response = client.map(
    url="https://docs.example.com"
)
print(response)
```

### research() - AI-Powered Research

```python
import time

# For comprehensive multi-topic research
result = client.research(
    input="Analyze competitive landscape for X in SMB market",
    model="pro"  # or "mini" for focused queries, "auto" when unsure
)
request_id = result["request_id"]

# Poll until completed
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
    time.sleep(10)
    response = client.get_research(request_id)

print(response["content"])  # The research report
```

Key parameters: `input`, `model` ("mini"/"pro"/"auto"), `stream`, `output_schema`, `citation_format`

See **[references/research.md](references/research.md)** for complete research reference.

## Detailed Guides

For complete parameters, response fields, patterns, and examples:

- **[references/sdk.md](references/sdk.md)** - Python & JavaScript SDK reference, async patterns, Hybrid RAG
- **[references/search.md](references/search.md)** - Query optimization, search depth selection, domain filtering, async patterns, post-filtering
- **[references/extract.md](references/extract.md)** - One-step vs two-step extraction, query/chunks for targeting, advanced mode
- **[references/crawl.md](references/crawl.md)** - Crawl vs Map, instru

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: tavily-search
description: |
  Use this skill whenever a task needs the web: searching for information, checking current facts or news, finding sources, reading a URL, finding a page on a site, or collecting many pages from a site. Use it for anything past your training data or anything the user wants verified online.
allowed-tools: Bash(tvly *)
---

# Tavily search

Use the `tavily_search`, `tavily_extract`, `tavily_map` and `tavily_crawl` tools if your tool list has them
(some clients add a prefix such as `mcp__tavily__`). Otherwise run `tvly <command> --json` directly; there's no
need to check for it first. If neither works, follow [setup](references/setup.md).

Parameters are named as in the API (`max_results`). The CLI spells them as flags (`--max-results`) with
comma-separated lists (`--include-domains sec.gov,reuters.com`). For exact parameters, read the tool schema,
run `tvly <command> --help`, or see the [API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search).

| You have | You need | Use |
|---|---|---|
| A question or topic | Sources, facts or news | Search |
| URLs | Their content | Extract |
| A site, not the exact page | The right page's URL | [Map](references/map.md) |
| A site section | Many of its pages | [Crawl](references/crawl.md) |

## Search

**Use advanced search.** Set `search_depth` to `advanced` (`--depth advanced` in the CLI) for every search
unless the user needs a fast answer to a simple lookup. It reaches more sources and ranks the passages that match your query.

**Write queries for a search engine.** Use the names and terms you expect on the page, not the user's whole
request. Split a question with several parts into one focused search per part. For a long written report,
search each part separately and extract the main sources for each before you write.

**Follow your leads.** When a result names a likely answer, test it right away: search that name with the
other details you know, or extract its page. Keep a lead that fits most details until a source contradicts it; a detail you can't confirm doesn't rule it out. When a search misses,
search the details again in their own words before adding names or filters you guessed, and build lists of
candidates from results, not memory. When a detail keeps coming back empty, work out what it refers to, such as
the role, event or term, and search for that.

Each result's `content` is already the passages that match your query; print it whole rather than cutting it short.

**Batch independent searches.** Issue the searches for one step together in one turn, one call each: separate
`tavily_search` calls with MCP tools, or separate Bash calls with the CLI, each holding a single `tvly` command.
MCP calls run in parallel; Bash calls run one after another but still use one turn. Don't add pipes, `&`, `$(...)`
or other programs to a `tvly` call, which make the client ask for permission. Put the query in single quotes:
`tvly search 'Rust 2024 edition release date' --depth advanced --max-results 10 --json`.

**Ask for 10 results.** Set `max_results` to 10 (`--max-results 10`). **Narrow before you widen.** Filters help more than raising `max_results` further. Use `time_range` or dates for
recent events or a stated period. Use `include_domains` when the answer lives on an official or named site; it
is a hard filter, so search again without it if it doesn't find the page.

**Keep large results on disk.** When a result is long, such as raw page content or a crawl, save it with
`-o <file>` and read the parts you need with your file-reading tool instead of printing it all. To reuse a file,
use the path you wrote; never look for it with a glob over temp folders, which can read another task's files. An
MCP result lands straight in your context, so keep those calls small.

**Read the results critically.** Count independent sources, not results. Treat a generated answer as a summary
to check, never as a source.

## Extract

Extract ret

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.