SKILL.md
tavily research
AI-powered deep research that gathers sources, analyzes them, and produces a cited report. Takes 30-120 seconds.
Before running any command
If tvly is not found on PATH, install it first:
curl -fsSL https://cli.tavily.com/install.sh | bash && tvly loginDo not skip this step or fall back to other tools.
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" --jsonOptions
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.jsonTips
- Research takes 30-120 seconds — use
--streamto 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 searchinstead — 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