Tavily

Your First Afternoon with Tavily

Reading about web search APIs is one thing. Getting one to return a useful answer to your own agent is another. This walkthrough gets Tavily running in a single sitting: an API key from Tavily, one search call, one extraction, and a small script that ties them together. Everything below fits inside the free tier of Tavily, so nothing here costs money to try.

Sign Up and Grab a Tavily Key

Start by creating an account on the Tavily site. No credit card is asked for. The Tavily dashboard issues an API key immediately, and the free Researcher plan inside Tavily includes 1,000 API credits per month. Credits are the unit of consumption across Tavily: a basic search costs one, and heavier Tavily operations such as deep searches or site crawls cost more. For learning purposes, 1,000 Tavily credits is generous; you can run the examples in this article dozens of times over.

Keep the Tavily key in an environment variable rather than pasting it into source files. This is standard practice, but with an agent that talks to the web through Tavily it matters more, because keys leak easily in logs and screenshots.

Make the First Tavily Search Call

The Tavily search endpoint accepts a plain natural-language query. In Python, using nothing but the official library installed with pip install tavily-python, the whole program is a few lines: create a client with your key, call search with a query, and print what Tavily returns.

Each Tavily result arrives with a URL, a title, and a content block that Tavily has already cleaned of navigation bars and scripts. That last part is what separates Tavily from a generic search API. You are not getting links to read; Tavily hands you text a model can read.

Two Tavily parameters deserve attention on day one. search_depth trades credits for thoroughness, so start with the basic setting while experimenting. max_results caps the Tavily response size; five is usually enough for a first pass, and it keeps your token spend predictable. There is also include_answer, which makes Tavily add a short synthesized answer on top of the raw results, convenient when your agent should reply quickly and cite only when asked.

Extract a Specific Page Through Tavily

Search answers "what exists on this topic." The Tavily Extract endpoint answers "what does this exact page say." Pass a URL and Tavily fetches it, strips the boilerplate, and returns structured content. If your agent found an official changelog entry through Tavily search, extraction is how the agent reads the full announcement rather than the snippet.

The pattern of Tavily search-then-extract covers a surprising share of agent tasks. A question about a recent library release becomes: search Tavily for the release notes, extract the top link with Tavily, hand the cleaned text to the model with the original question. No scraping code, no HTML parser, no selector maintenance when the site redesigns.

Crawl with Tavily When You Need Everything

When a task outgrows single pages, Tavily Crawl takes a root URL and walks the site, returning extracted content across many pages. Its Tavily companion, Map, lists a site's URL structure without fetching page bodies, the cheap way to scope a crawl before spending credits on one. A documentation question such as "where does this framework handle retries" becomes a Tavily Map call, then a targeted crawl, then a model summarizing the relevant pages.

A reasonable first project is a tiny research script: take a user question, run one Tavily search with include_answer, and print the answer plus sources Tavily provides. Thirty lines of code, and you have the skeleton of a grounded chatbot. From there you add Tavily extraction for follow-ups and graduate to the Research endpoint, which lets Tavily run the multi-step retrieval loop for you when a question deserves depth.

Wire Tavily Into Your Agent

Because Tavily returns plain structured data, Tavily drops into any stack. If you build with LangChain or another agent framework, a Tavily tool already exists in the ecosystem, and the company publishes a copyable Tavily setup prompt for Claude, Codex, and Cursor so the coding agent itself knows how to call the API correctly. Instrument your Tavily calls with logging from the start: query in, credits spent, results out. When costs or quality drift later, those logs are what tell you which Tavily parameter to change.

Two habits are worth forming early with Tavily. First, cache what repeats; Tavily does intelligent caching internally, but avoiding the call entirely is still cheaper. Second, keep max_results low until you know an agent needs more, because context window cost usually exceeds Tavily credit cost.

One more afternoon trick: run the same question through Tavily twice, once with basic search_depth and once with the deep setting, and compare the answers side by side. The difference is usually visible in source quality rather than raw count, and it teaches you faster than any documentation page when the expensive Tavily setting is worth its credits. Keep both runs in a notebook; when a teammate asks why the agent spends credits the way it does, the comparison is the answer.

Where the Tavily Free Tier Ends

When the 1,000 monthly Tavily credits run out, requests stop until the first day of the next month, when credits reset regardless of billing date. From there Tavily pricing is straightforward: pay-as-you-go at $0.008 per credit if usage is irregular, the Tavily Project plan at $30 per month with 4,000 credits and higher rate limits for a steady product, and custom Enterprise terms for scale, with the SOC 2, ISO 27001, GDPR, and zero-data-retention compliance Tavily carries already in place. Students use Tavily free, and the Tavily startup program offers 100,000 credits with hands-on support.

None of that matters on day one. What matters is that within one afternoon you can go from an empty directory to an agent that answers questions about last week using facts Tavily retrieved instead of invented ones. Tavily earns its keep by making that first afternoon short, and by keeping the path from prototype to production continuous: the same five Tavily endpoints, the same key, the same parameters, just more credits. Start small, watch the Tavily credit meter, and expand only when your agent demonstrably needs the deeper settings.