tavily-research

name	tavily-research
version	2.0
last_updated	2026-08-29T00:00:00.000Z
tags	["tavily","research","citations","synthesis","cli"]
description	Run Tavily's multi-source research workflow for comparisons, market analysis, literature-oriented exploration, or detailed cited reports. Use only when bounded search and extraction are insufficient.
license	MIT
compatibility	Requires the official Tavily CLI and authenticated Tavily access, or an active Tavily research surface; research jobs may consume additional time and API credits.

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.

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.

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.

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.