Tavily API - Complete Developer Guide to Web Search, Extraction, Crawling, Mapping & Research

What Tavily gives you

Tavily is built around a simple promise: your application can ask the web for information, and get back results that are ready to use in an AI workflow (RAG, agents, research assistants, support bots, dashboards). Tavily’s endpoints cover the full pipeline:

When Tavily is a good fit

Tavily is especially useful when you’re building an AI product that needs current information and you want a single provider to handle the messy parts: selecting sources, extracting readable content, and returning data in a format that’s easy to feed into a model.

Common use cases include:

• Agent web search (tools in LangChain/LlamaIndex/CrewAI, etc.) with configurable depth and domain targeting.
• RAG augmentation: search → extract → chunk → embed → store in a vector DB, then retrieve for grounded answers.
• Research reports: multi-step research that produces a structured report and source list.
• Competitive intelligence and market monitoring (news, finance topics, recent updates).
• Data enrichment: enrich a dataset with verified facts and source URLs.
• Internal knowledge bootstrapping: crawl and extract documentation sites, help centers, or product wikis.

Authentication (API key)

All Tavily endpoints are authenticated using an API key. You pass your key via an Authorization header using Bearer auth:

Authorization: Bearer tvly-YOUR_API_KEY

Tavily also supports an optional X-Project-ID header so you can track and organize usage by project when one API key is shared across multiple apps or environments.

X-Project-ID: your-project-id

Monthly free credits (starter usage)

Tavily’s platform provides a free tier that includes a monthly credit allowance (commonly shown as 1,000 free API credits per month with no credit card required on the quickstart page). You can use the /usage endpoint to monitor your key and account limits in real time.

Rate limits (RPM)

Tavily provides separate rate limits for development and production environments tied to your API key:

Access to production keys may require an active paid plan or PAYGO enabled (depending on your Tavily account configuration).

How credits are billed (the practical rules)

Tavily uses an API Credits system. Credits are consumed differently depending on endpoint and depth. Here is the most important mental model:

• Search: cost depends on search_depth (basic/fast/ultra-fast commonly 1 credit; advanced commonly 2 credits).
• Extract: billed per successful URL extraction in batches (e.g., every 5 successful URLs is 1 credit for basic, 2 credits for advanced).
• Map: billed per pages mapped (e.g., every 10 pages is 1 credit; mapping with instructions can cost more per 10 pages).
• Crawl: combines mapping + extraction costs (crawl cost = mapping cost + extraction cost).
• Research: dynamic pricing with min/max boundaries depending on model=mini vs model=pro.

Python SDK (sync + async)

Tavily provides a Python SDK with both synchronous and asynchronous clients. Typical usage looks like:

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")
res = client.search("What is Tavily?")
print(res)

For async workflows (high concurrency, background jobs), use the async client:

from tavily import AsyncTavilyClient

client = AsyncTavilyClient("tvly-YOUR_API_KEY")
res = await client.search("Latest AI developments")
print(res)

Proxies can also be configured at client instantiation if your environment requires it.

JavaScript / TypeScript SDK

Tavily offers a JavaScript SDK that supports search and extract functionality directly from JS/TS programs. A typical pattern is to instantiate a client with your API key, then call a method like search or extract.

const { tavily } = require("@tavily/core");

const client = tavily({ apiKey: "tvly-YOUR_API_KEY" });

async function run() {
  const res = await client.search({
    query: "What is Tavily?",
    max_results: 5,
    search_depth: "basic"
  });
  console.log(res);
}

run();

The JS client is commonly asynchronous by default, which fits serverless and modern Node runtimes nicely.

Search quality best practices

• Keep queries concise. Short, direct queries generally search better than long prompts.
• Use topic intentionally. Choose news for current events; finance for market data; general for everything else.
• Use time filters. If you care about freshness, set time_range or start_date/end_date.
• Constrain sources. Use include_domains for trusted sources or docs-only workflows.
• Start with basic depth. Move to advanced depth only when you need higher precision.

Extract / Crawl best practices

• Extract only what you need. Prefer “top URLs only” rather than bulk extraction.
• Choose the right format. Markdown is often best for downstream chunking; text can be simpler but may increase latency.
• Use advanced extraction sparingly. Advanced is great for tables and embedded content, but budget for it.
• Set timeouts. Use timeout so slow pages don’t stall your pipeline.
• Design for partial failure. Expect some URLs to fail; store failed URLs and retry later with backoff.

Common HTTP statuses you’ll see

• 400: invalid parameters, bad JSON, unsupported option, or constraints violated.
• 401/403: missing/invalid key, or lack of permission for a given feature/environment.
• 429: rate limited — implement retry with exponential backoff and jitter.
• 432/433: sometimes used for specialized error states (implementation-specific).
• 500: internal error — retry a small number of times; log request_id for support.

Retry + backoff (recommended)

The web is unreliable: sites time out, block requests, change HTML, or rate-limit aggressively. Your integration should assume some failures.

// PSEUDOCODE

maxAttempts = 4
baseDelayMs = 250

for attempt in 1..maxAttempts:
  res = callTavily()
  if res.status in [200, 201, 202]:
    return res
  if res.status == 429 or res.status >= 500:
    sleep( baseDelayMs * 2^(attempt-1) + randomJitter() )
    continue
  // 400/401/403: do not retry; fix request or auth
  throw error