Tavily API for AI agents: what a search costs in credits, and when it costs double

Your agent needs fresh facts from the web in a shape it can drop straight into context. Tavily is built for that: one call returns ranked results with the relevant chunks already extracted, and a second endpoint pulls the full text of any URL. The economics are simple on the surface, 1 credit per search, and full of multipliers underneath. By the end of this guide you will know why a research agent that "just searches and reads the top five pages" costs 3 credits per question, not 1, and which single flag doubles that again.

Why this matters for agents

When a person searches, one query and ten blue links is the whole transaction. When an agent searches, four things change.

The response is the context window. Tavily's default max_results is 10 in the API reference, and each result carries up to chunks_per_source: 3 extracted snippets. Ask for include_raw_content and each result also carries the whole page. Ten full pages of markdown can be more tokens than the model call that asked for them, so the cheap part (the search) can drive the expensive part (the LLM) (Search API reference).

Cost is per request, but the request shape sets the price. search_depth: "advanced" is 2 credits, and so is auto_parameters: true, which "may switch search_depth to advanced" on its own. The best-practices guide says basic is "the right default for general-purpose lookups" and advanced is for niche topics, very recent pages or multi-facet questions (best practices).

Rate limits are per key, not per agent. A development key gets 100 requests per minute and a production key 1,000; a 429 comes with a Retry-After header you should honour (rate limits). Ten parallel agents on one dev key share the same 100.

Partial failure is silent. Extract returns HTTP 200 with a failed_results[] array; the docs say to "check both arrays even when the response is HTTP 200", because results can be empty when every URL failed (Extract API reference). An agent that only reads results will happily summarise nothing.

Before spending, set search_depth explicitly, set max_results to what you will read, and pass include_usage: true so each response tells you what it cost.

What Tavily returns

A search request (POST /search) needs only query. The response has:

Request fields worth knowing: search_depth (basic, advanced, fast, ultra-fast), max_results (0 to 20), topic (general, news, finance), time_range or start_date/end_date, include_domains (up to 300) and exclude_domains (up to 150), country (only with topic: general), and max_age_hours (0 forces a live fetch, which "adds latency" but no credits). safe_search is not supported on fast or ultra-fast.

The extract endpoint (POST /extract) takes 1 to 20 urls and returns results[] with url and raw_content (markdown by default), plus failed_results[] with url and error. Output order "is not guaranteed", so match on url, not position. The default timeout is 10 seconds for basic and 30 for advanced, and you can set it anywhere from 1 to 60.

Two things are delayed. usage on an extract call "may be 0" until your successful extractions reach a multiple of 5, because billing is per 5 URLs. And score has no fixed threshold; the docs' own example filters at 0.7 but say "the ideal threshold depends on your use case".

The economics

Tavily bills in credits (credits and pricing, as of October 2026). Search: 1 credit at basic, fast or ultra-fast, 2 at advanced. Extract: 1 credit per 5 successful URLs at basic, 2 per 5 at advanced; failures are not charged. Credits cost $0.008 each pay as you go, $0.0075 on the $30 Project plan, $0.0067 on the $100 Bootstrap plan, $0.0058 on the $220 Startup plan and $0.005 on the $500 Growth plan. The free Researcher tier is 1,000 credits a month.

The comparison hides what each dollar buys. Exa charges $7 per 1,000 auto searches for up to 10 results, then $1 per 1,000 extra results, and $1 per 1,000 pages for contents. Perplexity is $5 per 1,000 POST /search requests and a request can carry up to five queries. Brave is $5 per 1,000 with $5 of free calls a month. SerpApi sells monthly plans only, $25 for 1,000 Google result pages. Tavily basic at $8 includes the extracted chunks, which on Exa is a second billed call.

The credit multipliers, per 1,000 calls:

Worked example: a research agent. Per question it runs one search and extracts the top 5 pages.

• Basic search (1) + basic extract of 5 URLs (1) = 2 credits = $0.016 per question. 1,000 questions = 2,000 credits = $16 pay as you go, or free for the first 500 on the Researcher tier.
• Advanced search (2) + basic extract (1) = 3 credits = $0.024. 1,000 questions = $24.
• Advanced search (2) + advanced extract (2) = 4 credits = $0.032. 1,000 questions = $32, exactly double the basic path, for the same number of HTTP calls.

If the agent instead sets include_raw_content: true on the search and skips extract, it pays 1 or 2 credits and gets full pages for every result, not just the top 5. Cheaper in credits, often far more expensive in LLM tokens.

How to call it from your agent

AMXP is in private preview. Once it opens, the flow for a news search looks like this:

const [tool] = await amxp.discover({ query: "web search with page content", provider: "tavily" })
const spec = await amxp.inspect(tool.id)   // parameters and per-call price
const run = await amxp.execute(tool.id, {
  query: "EU AI Act enforcement timeline",
  search_depth: "basic",      // 1 credit; never leave this to auto_parameters
  topic: "news",
  time_range: "week",
  max_results: 5,
  include_answer: false,
  include_usage: true,
})
// run.output.results[].content, run.output.usage.credits

With your own Tavily key, the direct call is a single request with a bearer token:

curl -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "EU AI Act enforcement timeline", "search_depth": "basic", "topic": "news", "max_results": 5, "include_usage": true}'

Then read the pages worth reading, in one call rather than five:

curl -X POST https://api.tavily.com/extract \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/a", "https://example.com/b"], "extract_depth": "basic", "format": "markdown"}'

What most people get wrong

Using advanced search by default. It is 2 credits, "highest relevance with increased latency". Reserve it for niche or very recent topics, and for queries that need chunks_per_source to work hard. Start every agent on basic and escalate only when results score low.

Leaving auto_parameters on. It costs 2 credits per request whatever it decides, and it can switch you to advanced. The reference says setting search_depth explicitly avoids the extra cost. If you want Tavily to pick topic and time_range, fine, but pin the depth.

Extracting one URL per call. Billing is per 5 successful URLs, so a loop that calls extract once per link pays the same per-5 credit but makes five times the HTTP calls against a 100 RPM dev limit. Batch up to 20 URLs per request.

Ignoring failed_results. A 200 with an empty results array is a valid response. Check both arrays and treat a URL in failed_results as unread, not as "nothing on that page".

Asking for 20 results and reading 3. The best-practices guide warns that setting max_results too high "may return lower-quality results", and every result adds tokens. Set max_results to the number you will actually pass to the model.

When to use something else

• Plain search engine results. SerpApi returns Google and other engines' result pages as JSON, which suits SEO and rank tracking better than LLM-ready chunks.
• Semantic or neural search. Exa is cheaper per search but bills contents separately. Perplexity Search API, Parallel, Linkup and Valyu are also agent-oriented search APIs worth comparing on your own queries.
• An independent index. Brave Search API runs its own web index at $5 per 1,000, with monthly free credit.
• Crawling whole sites. Firecrawl turns sites into clean markdown or JSON and is the natural fit when crawling, not searching, is the job.
• Steady, high volume. At 100,000 credits a month, Tavily's Growth plan brings a credit to $0.005, 37% below pay as you go. If Tavily is your agent's main search tool, a plan on your own account wins. AMXP is for the providers you call now and then, without opening another account.

Common questions

Can I try Tavily without an API key?

Yes. Tavily offers keyless access to Search and Extract: send the X-Tavily-Access-Mode: keyless header. It is free and rate-limited, uses the same response schema as keyed calls, and does not cover /crawl, /map or /research.

What is the difference between content and raw_content?

content holds the relevant chunks from each page, up to chunks_per_source of them (1 to 3, default 3). raw_content is the full page as markdown or text, and you only get it when you set include_raw_content.

How many URLs can one extract call take?

Up to 20. More than 20, an empty list, or no valid URLs returns a 400 whose detail.failed_results explains each rejection. Billing counts successful URLs only, in blocks of 5.

AMXP is in private preview; the flow above shows how it works through AMXP once it opens.