Research is the primitive that gives your agent eyes on the live web. Naive exposes three tools at different levels of depth and cost — web_search, read_url, and research — so the agent picks the right one for the job: a quick fact lookup, a single-page extract, or a multi-step synthesis with citations. Use the lightest tool that meets your needs to keep latency and cost low.
CLI First
# Web search
naive search "AI agent frameworks comparison 2026"
# Read a specific URL
naive search url https://example.com --extract "Main takeaways"
# Deep research
naive search research "Compare top AI agent frameworks in 2026" --depth thorough --wait
| Tool | Type | Description | Speed | Cost |
|---|
web_search | Core | Search the web for current information — returns ranked results with snippets | Fast (~1s) | 1 credit |
read_url | Core | Fetch a URL and extract main text content with optional AI focus | Fast (~2s) | 1 credit |
research | Core | Multi-step deep research — search, fetch, and synthesize with citations | Slow (~10-90s) | 3-8 credits |
web_search
Real-time web search. Returns titles, URLs, and snippets — no page fetching.
curl -X POST https://api.usenaive.ai/v1/search \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "AI agent frameworks comparison 2026",
"count": 5
}'
{
"results": [
{
"title": "The Best AI Agent Frameworks in 2026 - TechReview",
"url": "https://techreview.com/ai-agent-frameworks-2026",
"snippet": "We compared the top 10 AI agent frameworks across performance, ecosystem, and developer experience..."
},
{
"title": "LangChain vs CrewAI vs AutoGen: A Developer's Guide",
"url": "https://dev.to/comparison-langchain-crewai-autogen",
"snippet": "After building production agents with all three frameworks..."
}
],
"credits_used": 1
}
Parameters
| Param | Type | Required | Default | Description |
|---|
query | string | Yes | — | Search query |
count | number | No | 5 | Number of results (1-20) |
When to use
- Quick fact checks
- Finding URLs to read in detail
- Getting recent news or pricing
- Time-sensitive information your training data might not cover
read_url
Fetch a webpage and extract the main text content. Optionally uses AI to focus on a specific topic.
curl -X POST https://api.usenaive.ai/v1/search/url \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://techreview.com/ai-agent-frameworks-2026",
"extract": "pricing and free tiers"
}'
{
"url": "https://techreview.com/ai-agent-frameworks-2026",
"content": "# AI Agent Frameworks Pricing\n\nLangChain: Open source, free...\nCrewAI: Free tier available, Pro at $49/mo...",
"credits_used": 1
}
Parameters
| Param | Type | Required | Default | Description |
|---|
url | string | Yes | — | URL to fetch and extract |
extract | string | No | — | Focus question — AI extracts relevant sections only |
When to use
- Reading a specific article after
web_search
- Extracting structured data from a known URL
- Getting documentation or pricing from a product page
Local and private URLs (localhost, 127., 10., 192.168.*) are blocked for security.
research
Multi-step deep research: searches the web, fetches top results, and synthesizes a comprehensive answer with inline citations. This is the heavyweight tool — use it when you need a thorough, multi-source answer.
curl -X POST https://api.usenaive.ai/v1/search/research \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "What are the most effective go-to-market strategies for AI developer tools in 2026?",
"depth": "thorough"
}'
Depth Levels
| Depth | Behavior | Credits | Time |
|---|
quick | Inline response (search + synthesis) | 3 | ~5s |
thorough | Async job, more sources | 5 | ~45s |
exhaustive | Async job, max sources | 8 | ~90s |
thorough and exhaustive, you’ll get a 202 response with a job ID:
{
"job_id": "job-uuid",
"status": "processing",
"estimated_seconds": 45,
"hint": "Poll GET /v1/jobs/job-uuid for results."
}
{
"summary": "Based on analysis of current market trends...\n\n1. **Developer-first content marketing** — [1][2]\n2. **Open-source core with managed cloud** — [3]\n3. **Community-driven growth** — [4][5]",
"sources": [
{ "title": "GTM Playbook for Dev Tools", "url": "https://a16z.com/gtm-dev-tools" },
{ "title": "How Dev Tools Scale to $3B", "url": "https://techcrunch.com/dev-tools-growth" }
]
}
Use web_search → scan snippets for the answer.POST /v1/search { "query": "OpenAI API pricing 2026" }
Use web_search → read_url on the best result.POST /v1/search { "query": "payments API changelog" }
→ Found: https://docs.example.com/changelog
POST /v1/search/url { "url": "...", "extract": "May 2026 changes" }
Use research for end-to-end synthesis.POST /v1/search/research {
"query": "How are B2B SaaS companies using AI agents for support in 2026?",
"depth": "thorough"
}
Error Handling
| Error | Cause | Recovery |
|---|
insufficient_credits | Not enough credits | Check balance with GET /v1/status |
url_blocked | Target is a private/local address | Use a public URL |
fetch_failed | Could not reach the target URL | Try a different URL or use web_search |
provider_error | Search provider error | Retry after a few seconds |
Start with web_search. If snippets aren’t enough, follow up with read_url. Only use research when you need a synthesized multi-source answer — it’s significantly more expensive but produces better results for complex questions.
Typical Workflow
Agent receives task: "Research competitor pricing for our Q3 strategy"
│
├─ POST /v1/search → Find relevant sources
│ { query: "competitor SaaS pricing 2026" }
│ → 5 results with URLs
│
├─ POST /v1/search/url → Deep dive on best result
│ { url: "https://competitor.com/pricing",
│ extract: "pricing tiers and features" }
│ → Extracted pricing details
│
└─ POST /v1/search/research → Comprehensive analysis
{ query: "How does our pricing compare?",
depth: "thorough" }
→ Synthesized report with citations
