Search across Valyu’s comprehensive knowledge base including web content, academic journals, financial data, and proprietary datasets. The DeepSearch API returns AI ready search results that are perfect for RAG pipelines, AI agents, and applications.

​
Why Use the DeepSearch API

The DeepSearch API provides AI ready search results that enable:
  • 🔍 Comprehensive Coverage - Search web, academic journals, books, and live financial data
  • ⚡ Real-Time Results - Access up-to-the-minute information from sources
  • 🎯 Precise Filtering - Control sources, dates, relevance scores, and result count
  • 🛠️ RAG-Ready - Perfect for Retrieval-Augmented Generation and AI agent workflows

​
Key DeepSearch Features

Multi-Source Search

Search web content alongside academic papers, books, and financial market data in one API call.

AI Ready

Get AI ready search results that can you pass directly to your AI’s context window.

Source Control

Include or exclude specific domains, URLs, and datasets to focus on authoritative sources.

Date Filtering

Filter results by publication date to get recent or historical content.

​
Getting Started

​
Basic Search Query

Search across all available sources with a simple query: 
from valyu import Valyu

valyu = Valyu() # Uses VALYU_API_KEY from env

response = valyu.search(
query="latest developments in quantum computing",
max_num_results=5,
search_type="all",
)

for result in response["results"]:
print(f"Title: {result['title']}")
print(f"URL: {result['url']}")
print(f"Source: {result['source_type']}")
print(f"Content: {result['content'][:200]}...")
print("---")

​
Fast Mode for Reduced Latency

Enable fast mode for quicker search speed but shorter results. Best for general purpose queries: 
from valyu import Valyu

valyu = Valyu()

# Fast mode search for reduced latency

response = valyu.search(
query="latest market trends in tech stocks",
fast_mode=True, # Enable fast mode
max_num_results=5,
search_type="all",
)

for result in response["results"]:
print(f"Title: {result['title']}")
print(f"Source: {result['source_type']}")
print(f"Content: {result['content'][:200]}...")
print("---")
This returns raw search results with metadata, relevance scores, and full content for each match.

​
Search Type Options

Control which data sources to search:
TypeDescriptionBest For
allSearch web and proprietary sources (default)Comprehensive coverage
webWeb search onlyCurrent events, general topics
proprietaryAcademic, financial, and premium sources onlyResearch, technical analysis

​
Advanced Features

​
AI Agent vs User Queries

Optimize retrieval based on the caller type: 
from valyu import Valyu

valyu = Valyu()

# AI agent making a tool call

agent_response = valyu.search(
query="latest AI research papers",
is_tool_call=True, # Optimized for AI processing
max_num_results=10,
)

# Direct user query

user_response = valyu.search(
query="explain quantum computing basics",
is_tool_call=False, # Optimized for human consumption
max_num_results=5,
)

​
Response Length Control

Control how much content is returned per result: 
from valyu import Valyu

valyu = Valyu()

# Short snippets for quick overview

response = valyu.search(
query="renewable energy trends",
response_length="short", # ~25k characters per result
max_num_results=10,
)

# Full content for detailed analysis

response = valyu.search(
query="financial market analysis",
response_length="max", # Full content
max_num_results=3,
)

# Custom character limit

response = valyu.search(
query="technical documentation",
response_length=5000, # Exactly 5000 characters
max_num_results=5,
)
Response Length Options:
  • "short": ~25,000 characters per result
  • "medium": ~50,000 characters per result
  • "large": ~100,000 characters per result
  • "max": Full content available
  • Custom integer: Exact character count

​
Advanced Feature Guides

Check out our guides for other advanced features:

Source Filtering

Include or exclude specific domains and datasets - Control exactly which sources to search for more targeted results

Date Filtering

Filter by time periods - Focus on recent content or historical data with flexible date range controls

Prompting Guide

Craft effective search queries - Learn how to write queries that get the most relevant results

Tips & Tricks

Optimize your searches - Advanced techniques for better performance and cost control

​
Response Format

​
Standard Search Response

{
  "success": true,
  "results": [
    {
      "title": "Quantum Computing Breakthrough: IBM's 1000-Qubit Processor",
      "url": "https://example.com/quantum-breakthrough",
      "content": "IBM announced a major breakthrough in quantum computing with their new 1000-qubit processor that demonstrates unprecedented error correction capabilities...",
      "source_type": "web",
      "domain": "example.com",
      "published_date": "2024-11-15",
      "author": "Dr. Jane Smith",
      "estimated_reading_time": 8,
      "language": "en",
      "content_type": "article",
      "tags": ["quantum computing", "IBM", "technology"],
      "price_per_result": 0.003
    },
    {
      "title": "Quantum Algorithms for Optimization Problems",
      "url": "https://arxiv.org/abs/2024.quantum.algorithms",
      "content": "This paper presents novel quantum algorithms for solving complex optimization problems with applications in machine learning and operations research...",
      "source_type": "academic",
      "domain": "arxiv.org",
      "published_date": "2024-10-22",
      "author": "Prof. Michael Johnson et al.",
      "citation_count": 15,
      "journal": "ArXiv Preprint",
      "doi": "10.48550/arXiv.2024.quantum.algorithms",
      "price_per_result": 0.005
    }
  ],
  "search_metadata": {
    "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
    "total_results": 2,
    "query": "latest developments in quantum computing",
    "search_type": "all",
    "max_num_results": 5,
    "processing_time_ms": 1250,
    "sources_searched": ["web", "academic", "financial"],
    "results_by_source": {
      "web": 8,
      "academic": 4,
      "financial": 0
    },
    "total_cost_dollars": 0.012,
    "cost_per_1000_queries": 12.0,
    "total_characters": 15420,
    "currency": "USD"
  }
}

​
Key Response Fields

FieldDescription
titleArticle or document title
urlSource URL
contentExtracted text content
source_typeSource category: web, academic, financial
published_datePublication date (when available)
authorAuthor information (when available)
domainSource domain
price_per_resultCost for this specific result

​
Best Practices

  1. Be Specific: Use detailed queries for better search results
  2. Set Appropriate Price Limits: Balance cost with data quality needs
  3. Filter Results: Use parameters to get only the most relevant content
  4. Choose the Right Search Type: Match search_type to your use case
  5. Monitor Costs: Track price_per_result and total_cost_dollars in responses
  6. Optimize for Tool Calls: Set is_tool_call=true for AI agent usage
For detailed guidance on optimizing your searches, see our Tips & Tricks guide and Prompting Guide.

​
Error Handling

from valyu import Valyu

valyu = Valyu()

try:
    response = valyu.search(
        query="quantum computing applications",
        max_num_results=10,
        search_type="all",
    )

    if response.get("success"):
        for result in response["results"]:
            print(f"Found: {result['title']}")
            print(f"Source: {result['source_type']}")
    else:
        print(f"Search failed: {response.get('error', 'Unknown error')}")

except Exception as e:
    print(f"Request failed: {e}")

Try the DeepSearch API

Explore the complete API reference with interactive examples and detailed parameter documentation.

​
Next Steps

API Reference

Complete parameter documentation and examples

Python SDK

Easy integration with Python applications

TypeScript SDK

Type-safe integration for JavaScript/TypeScript

Integration Guides

Connect with LangChain, LlamaIndex, and more