tavily-dynamic-search

# WRONG — raw results flood your context
tvly search "quantum computing 2025" --json

# RIGHT — only your print() output enters context
tvly search "quantum computing 2025" --json 2>/dev/null | python3 -c "
import json, sys
data = json.load(sys.stdin)
for r in data['results']:
 print(f'[{r[\"score\"]:.2f}] {r[\"title\"]}')
 print(f' {r[\"url\"]}')
"

{
 "query": "string",
 "answer": "string | null",
 "results": [
 {
 "url": "string",
 "title": "string",
 "content": "string (snippet, ~500-1500 chars)",
 "score": 0.0-1.0,
 "raw_content": "string | null (full page, only with --include-raw-content)"
 }
 ],
 "response_time": 0.0
}

{
 "results": [
 {
 "url": "string",
 "title": "string",
 "raw_content": "string (full page markdown)",
 "images": []
 }
 ],
 "failed_results": [],
 "response_time": 0.0
}

tvly search "query" --json 2>/dev/null | python3 -c "
import json, sys
data = json.load(sys.stdin)
# your filtering code here
"

python3 Single-quoted heredocs (`<< 'PYEOF'`) don't interpret anything — no escaping needed. This is the default for most tasks.

 **Script mode** — only when you will reuse the same script across multiple turns. Do NOT write one-shot scripts to `/tmp/`. If you run it once, use a heredoc.

 **Important: save DATA to `/tmp/`, not CODE.** Writing `/tmp/tavily_results.json` (data for later turns) = good. Writing `/tmp/my_filter.py` (one-shot code) = wasteful — use a heredoc instead.

## Multi-turn iteration

For complex queries, you often need to **explore before you extract** — just like PTC, where the model searches, sees titles, decides which results to drill into, then extracts.

 The key: **save raw results to a file, then process them in separate steps.** The file is your persistent state between turns.

### Turn 1: Search and explore

 Search and print only titles + scores. Save raw results to disk for later turns:

python3 80 and any(kw in para.lower() for kw in
 ['toyota', 'quantumscape', 'samsung', 'commercializ', 'production']):
 print(para)
 print()

 print('---\n')
PYEOF

python3 **Single turn** (pipe mode or one script): when you know upfront what you're looking for. Specific factual queries, known keywords.

 **Multi-turn** (save + explore + extract): when you need to see what's available before deciding what to extract. Open-ended research, complex topics, queries where you don't know the right keywords yet.

## Examples

### Simple factual lookup (single turn, pipe mode)

### Financial data extraction (single turn, heredoc)

### Multi-source research (multi-turn)

 **Turn 1** — broad search + triage:

python3 100 and any(kw in para.lower() for kw in
 ['high-risk', 'prohibited', 'deadline', 'obligation',
 'compliance', 'penalty', 'fine', 'article']):
 print(para)
 print()

 print('---\n')
 except Exception:
 continue
PYEOF

python3 Each turn, you save data to `/tmp/`, decide what to explore next, and write new filtering code as heredocs. The raw data accumulates on disk; your context stays lean.

## Writing your filtering code

The Python you write IS the filtering logic. There are no fixed templates — you write code that makes sense for the specific query. Here are principles, not rules:

 **Triage first.** Inspect titles and scores before fetching full pages. Don't extract everything blindly.

 **Be specific.** A financial query should filter for numbers and financial terms. A technical query should look for code blocks and specifications. A news query should look for dates and quotes. Match your filtering to the query.

 **Structural filtering helps.** Skip lines shorter than ~50-80 chars (usually nav elements). Skip common boilerplate phrases. Keep headings and their following paragraphs. But these are starting points — adapt based on what you see.

 **Print structured output.** Format your output so it's easy to reason over:

 **Handle errors.** Pages fail, URLs 404, extractions timeout. Use try/except and skip failures:

 **Token budget awareness.** Your `print()` output is what enters your context. Target 150-600 tokens per source. If you're printing 5000+ chars from a single page, you're probably not filtering enough. But if a source has a critical data table, it's fine to keep more.

## Options

All standard `tvly search` options work:

 Option Description 
 `--max-results` Number of results (default: 5, max: 20) 
 `--depth` `ultra-fast`, `fast`, `basic` (default), `advanced` 
 `--time-range` `day`, `week`, `month`, `year` 
 `--include-domains` Comma-separated whitelist 
 `--exclude-domains` Comma-separated blacklist 
 `--include-raw-content` Full page content (`markdown` or `text`) 
 `--country` Boost results from country

## Fallback: jq

When `python3` is unavailable, use `jq` for basic filtering:

 jq can't do multi-step search-then-extract or complex filtering. Use it only for simple lookups.