tavily-ai/tavily-python

The Tavily Python SDK allows for easy interaction with the Tavily API, offering the full range of our search, extract, crawl, map, and research functionalities directly from your Python programs. Easily integrate smart search, content extraction, and research capabilities into your applications, harnessing Tavily's powerful features.

What is Tavily‑Python?

Tavily‑Python is an official Python SDK for the Tavily API. The API provides a suite of web‑search‑related services – plain search, question‑answering, content extraction, site crawling, site mapping, and automated research reports – that can be called from your Python code.

Key capabilities

Feature	What it does	Typical use
search	Returns a list of web results for a query.	Feed results to an LLM or display to a user.
qna_search	Gives a concise answer to a question (good for RAG).	Prompt‑engineering or chatbot back‑ends.
get_search_context	Returns a single context string built from the top results.	Directly inject into a Retrieval‑Augmented Generation pipeline.
extract	Pulls raw text (and optionally images) from up to 20 URLs.	Pre‑process documents before embedding or summarising.
crawl (invite‑only)	Traverses a site from a start URL, respecting depth/limit and custom instructions.	Build a focused dataset from a domain.
map (invite‑only)	Returns the hierarchical structure of a site.	Visualise site architecture or decide what to crawl.
research	Generates a multi‑source research report with citations; supports streaming and usage tracking.	Automated report generation for agents or analysts.
feedback	Sends per‑result scores and comments back to Tavily.	Improve ranking for your own agents or collect user feedback.

Getting started

pip install tavily-python

from tavily import TavilyClient

# With an API key (recommended for full feature set)
client = TavilyClient(api_key="tvly‑YOUR_KEY")

# Simple web search
results = client.search("Who is Lionel Messi?")
print(results)

You can also run keyless (no API key) mode, which only allows search and extract and is rate‑limited:

client = TavilyClient()  # no key
try:
    print(client.search("What is quantum computing?"))
except TavilyKeylessLimitError as e:
    print(e.retry_after_seconds, "seconds until next quota")

Advanced usage

Custom HTTP sessions – inject a pre‑configured requests.Session or httpx.AsyncClient (useful behind corporate gateways).
Metadata headers – optional project_id, session_id, human_id, client_name are sent as HTTP headers for tracking.
Streaming research – set stream=True to receive chunks as they are generated.
Usage/credits – call get_research(..., include_usage=True) to see how many credits a task consumed (free tier: 1 000 credits/month).

Who might use this?

LLM developers building Retrieval‑Augmented Generation pipelines that need a quick, reliable web search source.
Data engineers who want to scrape and extract content without writing their own crawlers.
Product teams adding “ask‑the‑web” features to SaaS apps.
Research assistants automating report generation with citations.

License & support

Licensed under MIT – free to use, modify, and redistribute.
For help, email support@tavily.com or join the Tavily Developer Community.

All details are taken directly from the repository’s README.