Tavily: The Web Search API for AI Agents

What Is Tavily?

Tavily is a web search API built for LLMs and autonomous agents rather than for humans reading a results page. One POST to https://api.tavily.com/search returns ranked results with the page content already extracted, an optional LLM-written answer, and a credit count for the request. The calling agent never has to scrape a page, strip the navigation, or decide which of ten blue links was worth opening.

That framing is the whole product. Tavily's own documentation describes it as "the first search engine for AI agents," optimized for LLMs rather than general web search, and says it absorbs the burden of searching, scraping, filtering, and extracting relevant information into a single API call. A conventional search API hands back links. Tavily hands back content a model can read.

Five endpoints cover the surface: /search for ranked results, /extract for pulling clean content out of URLs you already have, /map for discovering the page structure of a site, /crawl for walking that structure and extracting as it goes, and /research for longer multi-step research tasks that you create and then poll.

The Tavily API

Search is a POST with a bearer token. The parameters that matter are search_depth, which defaults to basic and doubles the credit cost at advanced, and max_results, which defaults to 5. Setting include_answer asks Tavily to synthesize an answer from the results. Setting include_raw_content returns the full page text instead of the extracted snippets.

curl -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer tvly-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "postgres logical replication failover 2026",
    "search_depth": "basic",
    "max_results": 5,
    "topic": "general",
    "include_answer": false,
    "include_raw_content": false
  }'

# Response fields:
#   query          the executed query
#   answer         LLM-generated answer, when include_answer is set
#   results        [{ title, url, content, score }]
#   images         query-related images
#   response_time  execution duration in seconds
#   usage          credit consumption for this request
#   request_id     unique request identifier

The score on each result and the usage block are the two fields worth wiring into your own telemetry. Score lets an agent drop weak results before they reach the model's context. Usage lets you attribute spend per request instead of reconciling a monthly credit total after the fact.

Other useful parameters: time_range defaults to null and restricts results by recency, include_domains defaults to an empty array and pins the search to specific sites, and chunks_per_source defaults to 3 and controls how much of each page comes back.

Tavily Pricing and Credits

Tavily bills in API credits, not tokens. That is unusual for an AI infrastructure product and it changes how you budget. A verbose page and a terse one cost the same to search. What varies is which endpoint you call and how deep you tell it to go.

Tavily documents crawl cost with a worked example. Crawling 10 pages with basic extraction is 3 credits: 1 for the mapping and 2 for the extraction. The same 10 pages with advanced extraction is 5 credits, 1 for mapping and 4 for extraction.

The Pay As You Go rate makes the arithmetic easy. At $0.008 per credit, a basic search is $0.008 and an advanced search is $0.016. An agent that fires 20 searches per task spends about $0.16 on retrieval before the model generates a token. The free tier's 1,000 credits cover roughly 1,000 basic searches per month, which is a prototype budget, not a production one.

Rate Limits

Tavily separates development keys from production keys, and production access requires an active paid plan or PAYGO enabled. This catches teams that prototype against a free key and then discover the ceiling on launch day.

Exceeding a limit returns HTTP 429 with a retry-after header giving the seconds to wait. Handle that header rather than backing off blindly. The crawl and research caps are the ones to design around, since they do not lift on a production key.

Tavily vs Other Web Search APIs

The category splits on one question: does the API return links or does it return content? Traditional search APIs return a SERP. You get titles, URLs, and snippets, and then you fetch and clean the pages yourself. Agent-oriented APIs like Tavily return extracted page content in the same response, and optionally a synthesized answer.

That difference shows up in your code as an entire pipeline you either write or skip: fetch, follow redirects, handle bot walls, strip boilerplate, dedupe, truncate to a token budget. Tavily's pitch is that the pipeline is the product and the ranked links are a commodity.

The billing model differs too. Most search APIs price per query. Tavily prices per credit, which lets one meter cover search, extraction, crawling, and multi-step research at proportional cost. A crawl that touches 50 pages is priced like 50 pages of work rather than like one query.

Web Search vs Code Search for Agents

An agent that fixes bugs and an agent that answers questions have the same shape and different retrieval needs. Both spend most of their turns looking for context. Research across coding agents puts that figure at 60% or more of turns, and the quality of retrieval determines whether the task succeeds. The open question is which corpus is being searched.

Tavily searches the open web. It is the right tool when the answer lives outside the model's training data: a library version released last month, a breaking change in a framework, a vendor's current pricing, a CVE published yesterday. Relevance ranking over web documents is exactly the right retrieval signal there.

WarpGrep searches a repository. Ranking is the wrong signal for code, because the answer is usually reached by following structure rather than by matching keywords. The query "how does the billing system handle failed payments" has no string to match. The logic spans a webhook handler, a retry module, and a notification path, connected by imports and call sites, not by shared vocabulary. WarpGrep runs an RL-trained search agent that issues up to 8 parallel tool calls per turn across up to 4 turns and returns precise file spans instead of whole files.

These compose rather than compete. A realistic agent trace hits both: search the web to learn that a dependency changed its API in the current major version, then search the repo to find every call site that has to change. Drop either one and the agent guesses.

The subagent detail is the one people miss. When the main coding model searches for itself, every dead end it reads stays in its context, and performance degrades as irrelevant content accumulates. Running search in an isolated context and returning only the surviving spans is why Anthropic measured a 90% improvement from multi-agent architecture. The same argument applies to web results: an agent that dumps ten full pages into its main context has paid for retrieval twice.

When to Use Which

Pick by where the answer lives, not by which tool you already wired up.

• Use Tavily when the fact is public and post-cutoff: current docs, release notes, pricing, news, competitive research, or anything a user asks about that happened recently.
• Use Tavily extract or crawl when you already know the URLs and need clean text, for example ingesting a documentation site or monitoring a changelog.
• Use WarpGrep when the answer is in a repository: locating a definition, tracing a call chain, finding every site a refactor touches, or gathering context before an edit.
• Use both for the common case, an agent that has to reconcile external documentation with internal implementation. Web search tells it what the API is supposed to do. Code search tells it what your code actually does.

One anti-pattern is worth naming. Do not point a web search API at your codebase by publishing it, and do not expect a code search tool to know about a framework released after its training data. Each fails silently in the other's domain, returning plausible results that are simply about something else.

Strengths and Limitations

Frequently Asked Questions

What is Tavily?

Tavily is a web search API built for LLMs and AI agents rather than for humans. A single POST to https://api.tavily.com/search returns ranked web results with the page content already extracted, plus an optional LLM-generated answer, so the calling agent does not have to scrape, clean, and filter pages itself. Alongside search it offers extract, crawl, map, and research endpoints.

How much does Tavily cost?

Tavily bills in API credits. The free Researcher plan includes 1,000 credits per month. Pay As You Go is $0.008 per credit. The Project plan includes 4,000 credits per month, and Enterprise pricing is custom. A basic search costs 1 credit and an advanced search costs 2, so at the Pay As You Go rate a basic search is $0.008 and an advanced search is $0.016.

What are Tavily's rate limits?

Development keys are limited to 100 requests per minute and production keys to 1,000 on the default endpoints. Crawl is capped at 100 requests per minute for both key types, and research task creation at 20 per minute. The usage endpoint allows 10 requests per 10 minutes. Exceeding a limit returns HTTP 429 with a retry-after header. Production access requires an active paid plan or PAYGO enabled.

Can Tavily search my codebase?

No. Tavily retrieves from the public web and has no view into a private repository. Web relevance ranking is also the wrong signal for code, where the answer is usually reached by following an import or a call chain rather than by matching keywords. Repository search is a separate tool: WarpGrep runs an RL-trained search agent over the repo itself and returns precise file spans.

Do AI agents need both web search and code search?

Usually yes, because they answer different questions. Web search covers facts outside the model's training data: a library released last month, a changed API, current pricing, a fresh CVE. Code search covers facts inside the repository: where a function is defined, what calls it, and which file spans a change has to touch. An agent with only web search guesses at your codebase. An agent with only code search cannot know about anything published after its training cutoff.

What is the difference between Tavily search and Tavily crawl?

Search takes a query and returns ranked results from across the web at 1 credit for basic depth. Crawl takes a starting URL and walks the site's structure, extracting content as it goes, and is billed as mapping cost plus extraction cost. Use search when you do not know which site has the answer. Use crawl when you already know the site and want its content.

Is there a free tier?

Yes. The Researcher plan is free and includes 1,000 API credits per month, which covers roughly 1,000 basic searches. It runs on a development key, capped at 100 requests per minute. Moving to a production key and its 1,000 requests per minute requires an active paid plan or PAYGO enabled.