Tavily

9 toolsAPI key

tavily_example.py

import os

from charter.packs import tavily

tavily.configure(api_key=os.environ["TAVILY_API_KEY"])

results = await tavily.search.ainvoke(query="latest AI news", search_depth="advanced")

Tavily is the web layer for AI agents: search when sources are unknown, extract when the URL is already selected, map and crawl when a whole site needs to be read, and research when the output should be a cited synthesis.

Authenticating

This pack takes an API key in Authorization, and configure() is optional when $TAVILY_API_KEY is set. There is no authorization server, no consent screen and no refresh — API keys is the whole story. The key is prefixed tvly-… and goes out as a bearer token.

The client

api_key_tool_factory is the whole client: a thin wrapper over httpx that attaches your key and these endpoint constants to each request. No vendor SDK enters your dependency tree.

import os

from charter import api_key_tool_factory

api_key = os.environ["TAVILY_API_KEY"]

tavily_api_client = api_key_tool_factory(
    base_url="https://api.tavily.com/",
    api_key_headers={"Authorization": f"Bearer {api_key}"},
    body_format="json",
    query_format="repeat",
    body_case="snake",
    query_case="snake",
    path_case="snake",
    # this API reports failure with an HTTP status code
    envelope=None,
)

import os

from charter.packs import tavily

tavily.configure(api_key=os.environ["TAVILY_API_KEY"])

# The base URL, the casing, the envelope and the pagination are
# already declared. 9 tools, ready to hand to a model:
tools = tavily.TOOLS

Tools

Each is a Tool, called with ainvoke as in the snippet above.

SearchsearchPOSTExecute a real-time web search optimized for AI agents.ExtractextractPOSTExtract clean markdown or text from one or more known URLs.CrawlcrawlPOSTGraph-based website traversal with built-in extraction.MapmapPOSTDiscover URLs on a site without extracting content.Researchresearch_createPOSTCreate an async research task that searches, analyzes sources, and generates a cited report.research_getGETRetrieve the status and results of a research task by request_id.UsageusageGETGet API key and account usage for the current billing cycle, broken down by endpoint type.logsPOSTRetrieve per-request usage logs for API keys under your account.org_usagePOSTRetrieve organization-wide usage, PayGo USD cost, and request counts across all API keys.

What each tool is for

search is the starting point when sources are unknown or current web context is needed. Prefer search_depth="advanced" with chunks_per_source=3 for stronger evidence per source. extract reads one or more known URLs as markdown or text. Use it after search when the URL is already selected. map discovers URLs on a site without extracting content — useful before crawl to understand structure. crawl traverses a site graph and extracts page content. Use when many pages on a site need to be read. research_create starts an async research task that searches, analyzes sources, and generates a cited report. Poll with research_get until status is completed. SSE streaming is not exposed as a tool. usage, logs, and org_usage report credit consumption. logs requires a paid plan or pay-as-you-go; org_usage is enterprise-only and must authenticate with the organization owner’s personal API key.

Gotchas

The wire is snake_case throughout

Parameters, bodies and query strings are all snake_case. Tavily ignores parameters it does not recognise, so a misspelled filter silently drops rather than failing.

Research is async

research_create returns a request_id. Poll with research_get — HTTP 202 means still running; HTTP 200 with status: completed carries the report.

Credits vary by depth

Search costs 1 credit for basic/fast/ultra-fast and 2 for advanced. Extract bills per five successful URLs; crawl and map bill per ten pages.

OAuth packs

API-key packs

Authenticating

The client

Tools

What each tool is for

Gotchas

​Authenticating

​The client

​Tools

​What each tool is for

​Gotchas

​Related

Authenticating

The client

Tools

What each tool is for

Gotchas

Related