tavily research

AI-powered deep research that gathers sources, analyzes them, and produces a cited report. Takes 30-120 seconds.

Before running any command

Check tvly --version and tvly --status first. If the CLI is missing, use a reviewed installation method:

uv tool install tavily-cli
# or: python -m pip install --user tavily-cli

Authenticate with tvly login or an approved environment secret. Never expose a real API key in commands, logs, files, or chat.

See tavily-cli for alternative install methods and auth options.

When to use

• You need comprehensive, multi-source analysis
• The user wants a comparison, market report, or literature review
• Quick searches aren't enough — you need synthesis with citations
• Step 5 in the workflow: search → extract → map → crawl → research

Quick start

# Basic research (waits for completion)
tvly research "competitive landscape of AI code assistants"

# Pro model for comprehensive analysis
tvly research "electric vehicle market analysis" --model pro

# Stream results in real-time
tvly research "AI agent frameworks comparison" --stream

# Save report to file
tvly research "fintech trends 2025" --model pro -o fintech-report.md

# JSON output for agents
tvly research "quantum computing breakthroughs" --json

Options

Option	Description
--model	mini, pro, or auto (default)
--stream	Stream results in real-time
--no-wait	Return request_id immediately (async)
--output-schema	Path to JSON schema for structured output
--citation-format	numbered, mla, apa, chicago
--poll-interval	Seconds between checks (default: 10)
--timeout	Max wait seconds (default: 600)
-o, --output	Save output to file
--json	Structured JSON output

Model selection

Model	Use for	Speed
mini	Single-topic, targeted research	~30s
pro	Comprehensive multi-angle analysis	~60-120s
auto	API chooses based on complexity	Varies

Rule of thumb: "What does X do?" → mini. "X vs Y vs Z" or "best way to..." → pro.

Async workflow

For long-running research, you can start and poll separately:

# Start without waiting
tvly research "topic" --no-wait --json    # returns request_id

# Check status
tvly research status <request_id> --json

# Wait for completion
tvly research poll <request_id> --json -o result.json

Tips

• Research takes 30-120 seconds — use --stream to see progress in real-time.
• Use --model pro for complex comparisons or multi-faceted topics.
• Use --output-schema to get structured JSON output matching a custom schema.
• For quick facts, use tvly search instead — research is for deep synthesis.
• Read from stdin: echo "query" | tvly research - --json

See also

• tavily-search — quick web search for simple lookups
• tavily-crawl — bulk extract from a site for your own analysis

Anti-Patterns

• Starting a long or higher-cost research job for a fact that bounded search can answer.
• Using an underspecified topic that invites uncontrolled scope or irrelevant synthesis.
• Treating the generated report as authoritative without checking its cited sources.
• Claiming completion from a request identifier before the job reaches a terminal success state.

Verification Protocol

Before claiming Tavily research succeeded:

1. Pass/fail: The research question, scope, model, citation format, and output destination are explicit.
2. Pass/fail: The user-requested depth justifies research rather than search or extraction.
3. Pass/fail: The job reaches a completed state and the final output is preserved when requested.
4. Pass/fail: Material claims and citations are spot-checked against the linked sources.
5. Pressure test: Handle timeout, failed status, contradictory sources, or incomplete citations without fabricating a conclusion.
6. Success metric: Report job state, selected model, saved artifact if any, checked sources, and remaining uncertainty.

<!-- MCP:START --> <!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/tavily-research and restart Codex after major changes.

<!-- PORTABILITY:END -->

MCP Availability And Fallback

Preferred MCP Server: Tavily MCP Server

• Fallback prompt: "Use the Tavily Research skill without MCP. Run a scoped tvly research job, poll it to a terminal state, keep secrets out of output, verify important citations, and report the job and artifact evidence."
• If the MCP server does not expose research, use the official CLI or SDK. If no authenticated surface exists, report the blocker.
• Do not claim completion from a non-terminal request identifier.

<!-- MCP:END -->

Related Skills

• tavily-search: Answer smaller current-information questions before escalating.
• tavily-dynamic-search: Perform agent-controlled multi-step source triage and extraction.
• documentation-verification: Check report citations and source links.