Search the web and get LLM-optimized results. Preferred over web-search when you need structured relevance scoring, domain filtering, or time-range filtering without spinning up a local browser.
Authentication
Set TAVILY_API_KEY in ~/.openclaw/.env.local:
TAVILY_API_KEY=tvly-your-api-key-here
Get a key at https://tavily.com (1,000 free credits/month).
When to Use This Skill
- Finding current news, events, or information beyond your knowledge cutoff
- Researching a topic from trusted/specific domains
- Time-scoped queries (e.g. "past week", "past month")
- When you need relevance scores to rank and filter results
- Quick factual lookups where browser automation would be overkill
Prefer tavily-research for deep multi-source synthesis or market analysis.
Quick Start
# Basic search
curl -s -X POST https://api.tavily.com/search \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "latest Claude model releases 2025", "max_results": 5}'
API Reference
Endpoint: POST https://api.tavily.com/search
Request Fields
| Field | Type | Default | Description |
|---|---|---|---|
query |
string | Required | Search query (keep under 400 chars) |
max_results |
integer | 10 | Max results returned (1–20) |
search_depth |
string | "basic" |
ultra-fast / fast / basic / advanced |
topic |
string | "general" |
Search topic category |
time_range |
string | null | day / week / month / year |
start_date |
string | null | Return results after this date (YYYY-MM-DD) |
end_date |
string | null | Return results before this date (YYYY-MM-DD) |
include_domains |
array | [] |
Restrict to these domains (max 300) |
exclude_domains |
array | [] |
Exclude these domains (max 150) |
country |
string | null | Boost results from a specific country |
include_raw_content |
boolean | false | Include full page content in results |
include_images |
boolean | false | Include image results |
Response Format
{
"query": "latest Claude model releases 2025",
"results": [
{
"title": "Page Title",
"url": "https://example.com/page",
"content": "Extracted text snippet...",
"score": 0.91
}
],
"response_time": 1.2
}
Search Depth Guide
| Depth | Latency | Use When |
|---|---|---|
ultra-fast |
Lowest | Real-time chat, quick lookups |
fast |
Low | Latency matters but need chunks |
basic |
Medium | General-purpose (default) |
advanced |
Higher | Precision critical, best relevance |
Examples
Recent news with time filter
curl -s -X POST https://api.tavily.com/search \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "AI agent frameworks news",
"time_range": "week",
"max_results": 10
}'
Domain-restricted search
curl -s -X POST https://api.tavily.com/search \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Python async patterns",
"include_domains": ["docs.python.org", "realpython.com", "github.com"],
"search_depth": "advanced"
}'
With full page content
curl -s -X POST https://api.tavily.com/search \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "openclaw agent config format",
"max_results": 3,
"include_raw_content": true
}'
Tips
- Keep queries under 400 characters — think search terms, not prompts
- Break complex topics into multiple targeted sub-queries
- Use
include_domainsto focus on authoritative sources - Use
scorefield (0–1) to filter low-relevance results; discard below 0.5 - Use
time_rangewhen the user asks about recent events or news advanceddepth is recommended when result quality matters more than speed