Search Quickstart

Search across web content, academic journals, financial data, and proprietary datasets. The DeepSearch API returns results ready for RAG pipelines, AI agents, and applications.

What You Can Do

Search everything - Web, research journals, books, and live financial data in one call
Get real-time results - Up-to-the-minute information from all sources
Filter precisely - Control sources, dates, relevance scores, and result count
Feed your AI - Results formatted for LLM context windows

Features

Multi-Source Search

Search web, research papers, books, and financial data in one API call.

AI Ready

Results go straight into your AI’s context window.

Source Control

Include or exclude specific domains, URLs, and datasets.

Date Filtering

Filter by publication date for recent or historical content.

Getting Started

Basic Search

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

Use fast mode for quicker responses with shorter results. Good for general queries:

from valyu import Valyu

valyu = Valyu()

response = valyu.search(
    query="latest market trends in tech stocks",
    fast_mode=True,
    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("---")

Search Types

Type	What it searches	Use for
`all`	Web and proprietary sources (default)	Comprehensive coverage
`web`	Web only	Current events, general topics
`proprietary`	Research, financial, and premium sources	Research, technical analysis
`news`	News articles only	Current news and journalism

Advanced Features

AI Agent vs User Queries

Set is_tool_call based on who’s making the request:

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,  # Optimised for AI
    max_num_results=10,
)

# User query
user_response = valyu.search(
    query="explain quantum computing basics",
    is_tool_call=False,  # Optimised for humans
    max_num_results=5,
)

Response Length

Control how much content comes back per result:

from valyu import Valyu

valyu = Valyu()

# Short snippets
response = valyu.search(
    query="renewable energy trends",
    response_length="short",
    max_num_results=10,
)

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

# Custom limit
response = valyu.search(
    query="technical documentation",
    response_length=5000,  # Exactly 5000 characters
    max_num_results=5,
)

Options:

"short": ~25,000 characters per result
"medium": ~50,000 characters per result
"large": ~100,000 characters per result
"max": Full content
Custom integer: Exact character count

100 Results

The Search API supports up to 100 results per query. This requires the increased_max_results permission on your API key. To enable 100 results:

Go to API Key Management
Request the increased_max_results permission
Create a new API key after approval

Without this permission, the default maximum is 20 results per query.

from valyu import Valyu

valyu = Valyu()  # Use API key with increased_max_results permission

response = valyu.search(
    query="renewable energy innovations 2025",
    max_num_results=100,  # Requires increased_max_results permission
)

print(f"Retrieved {len(response['results'])} results")

More Guides

Source Filtering

Include or exclude specific domains and datasets

Date Filtering

Filter by time periods

Prompting Guide

Write queries that get better results

Tips & Tricks

Optimise performance and control costs

Response Format

Example Response

{
  "success": true,
  "error": "",
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "query": "latest developments in quantum computing",
  "results": [
    {
      "title": "Quantum Computing Breakthrough: New Error Correction Method",
      "url": "https://nature.com/articles/quantum-error-correction-2024?utm_source=valyu",
      "content": "Researchers at MIT have developed a quantum error correction method that reduces error rates by 90% while maintaining computational speed...",
      "description": "Major breakthrough in quantum error correction methodology",
      "source": "academic",
      "price": 0.005,
      "length": 15420,
      "data_type": "unstructured",
      "source_type": "paper",
      "publication_date": "2024-03-15",
      "id": "https://nature.com/articles/quantum-error-correction-2024",
      "image_url": {
        "main": "https://nature.com/quantum-diagram.jpg"
      },
      "relevance_score": 0.94
    },
    {
      "title": "IBM Announces 1000-Qubit Quantum Processor",
      "url": "https://techcrunch.com/2024/05/12/ibm-quantum-1000-qubit?utm_source=valyu",
      "content": "IBM has unveiled its latest quantum processor featuring over 1000 qubits...",
      "description": "IBM's latest quantum hardware milestone announcement",
      "source": "web",
      "price": 0.003,
      "length": 8950,
      "data_type": "unstructured",
      "source_type": "website",
      "publication_date": "2024-05-12",
      "id": "https://techcrunch.com/2024/05/12/ibm-quantum-1000-qubit",
      "image_url": {
        "main": "https://techcrunch.com/ibm-quantum-chip.jpg"
      },
      "relevance_score": 0.87
    }
  ],
  "results_by_source": {
    "academic": 1,
    "web": 1
  },
  "total_results": 25,
  "total_cost_dollars": 0.008,
  "total_characters": 24370
}

Top-level Fields

Field	Description
`success`	Whether the search completed successfully
`error`	Empty on success; error message otherwise
`tx_id`	Transaction ID for tracing and support
`query`	The processed search query
`results`	Array of result objects, ranked by relevance
`results_by_source`	Count of results per source type
`total_results`	Total matches available
`total_cost_dollars`	Total cost in USD
`total_characters`	Total characters across all results
`fast_mode`	Present when fast mode was used

Result Fields

Field	Description
`title`	Document or article title
`url`	Canonical URL (may include tracking parameters)
`content`	Extracted text, trimmed per `response_length`
`description`	Brief summary
`source`	Source category: `web`, `academic`, etc.
`price`	Cost in USD for this result
`length`	Character count
`data_type`	Data type (e.g., `unstructured`)
`source_type`	Specific source classification (see Source types)
`publication_date`	ISO 8601 date when available
`id`	Stable identifier
`image_url`	Extracted images
`relevance_score`	Score between 0 and 1

Source Types

Type	Datasets	Description
`general`	`valyu-wikipedia` and similar corpora	General knowledge (e.g., Wikipedia)
`website`	Brave web search, Spider scraper, LinkedIn processor	Web articles
`forum`	Brave QA hits	Community Q&A snippets
`paper`	`valyu/valyu-arxiv` and academic indexes	Academic papers (ArXiv, etc.)
`data`	Finance server integrations	Market data and analytics
`report`	`valyu/valyu-sec-filings`	SEC regulatory filings
`health_data`	WHO Global Health Observatory	Global health indicators
`clinical_trial`	`valyu/valyu-clinical-trials`	Clinical trial summaries from ClinicalTrials.gov
`drug_label`	`valyu/valyu-drug-labels`	FDA drug labels from DailyMed
`grants`	NIH RePORTER	NIH funding data

Best Practices

Be specific - Detailed queries get better results
Set price limits - Balance cost with quality
Use filters - Get only what you need
Match search type - Pick search_type based on your use case
Track costs - Check total_cost_dollars in responses
Set is_tool_call=true - For AI agent usage

See our Tips & Tricks and Prompting Guide for more.

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

Full API reference with interactive examples

Next Steps

API Reference

Complete parameter documentation

Python SDK

Python integration

TypeScript SDK

TypeScript integration

Integrations

LangChain, LlamaIndex, and more

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Important Updates

Account & Pricing

Search Quickstart

What You Can Do

Features

Multi-Source Search

AI Ready

Source Control

Date Filtering

Getting Started

Basic Search

Fast Mode

Search Types

Advanced Features

AI Agent vs User Queries

Response Length

100 Results

More Guides

Source Filtering

Date Filtering

Prompting Guide

Tips & Tricks

Response Format

Example Response

Top-level Fields

Result Fields

Source Types

Best Practices

Error Handling

Try the DeepSearch API

Next Steps

API Reference

Python SDK

TypeScript SDK

Integrations

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Important Updates

Account & Pricing

​What You Can Do

​Features

Multi-Source Search

AI Ready

Source Control

Date Filtering

​Getting Started

​Basic Search

​Fast Mode

​Search Types

​Advanced Features

​AI Agent vs User Queries

​Response Length

​100 Results

​More Guides

Source Filtering

Date Filtering

Prompting Guide

Tips & Tricks

​Response Format

​Example Response

​Top-level Fields

​Result Fields

​Source Types

​Best Practices

​Error Handling

Try the DeepSearch API

​Next Steps

API Reference

Python SDK

TypeScript SDK

Integrations

What You Can Do

Features

Getting Started

Basic Search

Fast Mode

Search Types

Advanced Features

AI Agent vs User Queries

Response Length

100 Results

More Guides

Response Format

Example Response

Top-level Fields

Result Fields

Source Types

Best Practices

Error Handling

Next Steps