Agent API

Drop-in replacements for Tavily's agent endpoints. Switch with a single import change — same request/response format.

Agent Search

POST /api/v1/agent/search

AI-optimized web search with optional answer generation. Fully Tavily-compatible.

Body Parameters

Parameter	Type	Default	Description
`query`	string	required	Search query
`search_depth`	string	`"basic"`	`"basic"`, `"advanced"`, `"fast"`, `"ultra-fast"`
`max_results`	integer	`5`	Max results (1-20)
`topic`	string	`"general"`	`"general"`, `"news"`, `"finance"`
`include_answer`	boolean\|string	`false`	`true`, `"basic"`, `"advanced"`, `"production"`
`include_raw_content`	boolean\|string	`false`	`true`, `"markdown"`, `"text"`
`include_images`	boolean	`false`	Include image results
`include_image_descriptions`	boolean	`false`	AI-generated image descriptions
`include_domains`	string[]	—	Only search these domains
`exclude_domains`	string[]	—	Exclude these domains
`rerank`	boolean	`false`	Re-rank results by relevance
`model`	string	—	`"auto"`, `"speed"`, `"quality"`, `"reasoning"`, `"production"`
`check_safety`	boolean	`false`	Run safety check on query

Example Request

curl -X POST 'https://api.unsearch.dev/api/v1/agent/search' \
  -H 'X-API-Key: sk_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What is retrieval augmented generation?",
    "search_depth": "advanced",
    "include_answer": true,
    "max_results": 5
  }'

Response

{
  "query": "What is retrieval augmented generation?",
  "answer": "Retrieval Augmented Generation (RAG) is a technique that combines...",
  "images": [],
  "results": [
    {
      "title": "Understanding RAG",
      "url": "https://example.com/rag",
      "content": "Full content of the page...",
      "score": 0.95,
      "raw_content": "Raw markdown content..."
    }
  ],
  "response_time": 1.23,
  "model_used": "quality",
  "query_complexity": "moderate"
}

Agent Extract

POST /api/v1/agent/extract

Extract structured content from one or more URLs.

Body Parameters

Parameter	Type	Default	Description
`urls`	string[]	required	URLs to extract (max 20)
`include_images`	boolean	`false`	Include images
`extract_depth`	string	`"basic"`	`"basic"` or `"advanced"`

Example Request

curl -X POST 'https://api.unsearch.dev/api/v1/agent/extract' \
  -H 'X-API-Key: sk_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://example.com/article"],
    "extract_depth": "advanced"
  }'

Response

{
  "results": [
    {
      "url": "https://example.com/article",
      "raw_content": "# Article Title\n\nFull markdown content...",
      "images": ["https://example.com/img1.png"],
      "failed": false
    }
  ],
  "failed_urls": [],
  "response_time": 0.87
}

Agent Research

POST /api/v1/agent/research

Deep multi-step research with AI analysis. UnSearch exclusive — not available in Tavily.

Body Parameters

Parameter	Type	Default	Description
`query`	string	required	Research query
`depth`	string	`"standard"`	`"quick"`, `"standard"`, `"deep"`, `"comprehensive"`
`max_sources`	integer	`10`	Max sources to analyze
`include_analysis`	boolean	`true`	Include detailed analysis
`include_summary`	boolean	`true`	Include executive summary
`focus_areas`	string[]	—	Specific areas to focus on

Example Request

curl -X POST 'https://api.unsearch.dev/api/v1/agent/research' \
  -H 'X-API-Key: sk_live_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "State of AI agents in enterprise 2025",
    "depth": "deep",
    "max_sources": 15,
    "focus_areas": ["adoption", "ROI", "challenges"]
  }'

Response

{
  "query": "State of AI agents in enterprise 2025",
  "executive_summary": "AI agents are seeing rapid enterprise adoption...",
  "detailed_analysis": "## Adoption Trends\n\n...",
  "key_findings": [
    "73% of enterprises plan to deploy AI agents by 2026",
    "Average ROI of 340% reported by early adopters"
  ],
  "sources": [
    {
      "title": "Enterprise AI Report 2025",
      "url": "https://example.com/report",
      "content": "...",
      "score": 0.92
    }
  ],
  "methodology": {
    "queries_executed": 8,
    "sources_analyzed": 15,
    "depth": "deep"
  },
  "model_used": "quality",
  "response_time": 12.5
}

Migration from Tavily

# Before (Tavily)
from tavily import TavilyClient
client = TavilyClient(api_key="tvly-...")

# After (UnSearch) — same API
from unsearch import UnSearch
client = UnSearch(api_key="sk_live_...")

# Identical usage
results = client.search("query", include_answer=True)
extracted = client.extract(urls=["https://example.com"])

// Before (Tavily)
import { tavily } from "@tavily/core";
const client = tavily({ apiKey: "tvly-..." });

// After (UnSearch)
import { UnSearch } from "unsearch";
const client = new UnSearch({ apiKey: "sk_live_..." });

// Same methods
const results = await client.search("query", { includeAnswer: true });

Agent API

On this page