Search API | Python SDK

Search across web and proprietary data sources, returning content optimized for AI applications and RAG pipelines.

Wire up Valyu Search with the Python SDK.

Basic usage

from valyu import Valyu

valyu = Valyu()

response = valyu.search("What are the latest developments in quantum computing?")

print(f"Found {len(response.results)} results")
for result in response.results:
    print(result.title, "-", result.url)
    print(result.content[:200], "...")

Common patterns

# Fast mode - lower latency, shorter content
valyu.search(query, fast_mode=True)

# Restrict to specific sources (datasets, domains, or presets)
valyu.search(
    "quantum computing applications",
    included_sources=["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
    response_length="medium",
)
# ...or exclude sources instead (use one or the other, not both)
valyu.search(query, excluded_sources=["example.com"])

# Expand PubMed coverage while retaining full-text chunks where available
valyu.search(
    "clonal hematopoiesis cardiovascular disease",
    included_sources=["valyu/valyu-pubmed"],
    include_abstracts=True,
)

# Bias ranking without hard filtering (-5 demote ... +5 boost)
valyu.search(
    "climate change research",
    source_biases={"nasa.gov": 5, "noaa.gov": 3, "example.com": -4},
)

# Filter by country and date range
valyu.search(
    "renewable energy policies",
    country_code="US",
    start_date="2024-01-01",
    end_date="2024-12-31",
)

# News mode (up to 100 results with the increased_max_results permission)
valyu.search("AI breakthroughs", search_type="news", max_num_results=50)

Source biases support URL-path specificity - the most specific match wins ({"nih.gov": 2, "nih.gov/research": -3}).

Building a multi-step research flow on top of Search? Consider DeepResearch - a cost-effective autonomous agent purpose-built for reports, diligence, and market sizings.

Reference

Parameters

query (str, required) - the search query. See the Prompting Guide.

Parameter	Type	Description	Default
`search_type`	`"web"` \| `"proprietary"` \| `"all"` \| `"news"`	Which sources to search	`"all"`
`max_num_results`	int	Results to return (1-20, up to 100 with the increased_max_results permission)	10
`max_price`	float	Max cost per thousand retrievals (CPM). When omitted, all sources are searched regardless of cost	None
`is_tool_call`	bool	`True` for AI agents/tools, `False` for direct user queries	True
`relevance_threshold`	float	Minimum relevance score (0.0-1.0)	0.5
`included_sources`	List[str]	Sources to search within (dataset ids, domains, or presets)	None
`excluded_sources`	List[str]	Sources to exclude	None
`source_biases`	Dict[str, int]	Bias ranking per source (-5 to +5) without hard filtering	None
`instructions`	str	Natural-language instructions to rank by intent. Ignored in fast mode	None
`category`	str	Deprecated. Use `instructions`	None
`start_date` / `end_date`	str	Date filter (`YYYY-MM-DD`)	None
`country_code`	str	2-letter ISO country code to bias results	None
`response_length`	str \| int	`"short"` (25k), `"medium"` (50k), `"large"` (100k), `"max"` (full), or a custom character count	`"short"`
`include_abstracts`	bool	Expand PubMed coverage to the complete abstract corpus; retain full-text chunks where available	False
`fast_mode`	bool	Reduced latency, shorter results	False
`url_only`	bool	Return URLs only (no content). Applies when `search_type` is `"web"` or `"news"`	False

Response format

class SearchResponse:
    success: bool
    error: Optional[str]
    tx_id: str
    query: str
    results: List[SearchResult]
    results_by_source: ResultsBySource
    total_deduction_dollars: float
    total_characters: int

class SearchResult:
    title: str
    url: str
    content: str
    description: Optional[str]
    source: str
    price: float
    length: int
    relevance_score: float
    data_type: Optional[str]  # "structured" | "unstructured"
    # Academic/proprietary sources also populate:
    publication_date: Optional[str]
    abstract: Optional[str]
    authors: Optional[List[str]]
    citation: Optional[str]
    citation_count: Optional[int]
    doi: Optional[str]
    references: Optional[str]
    metadata: Optional[Dict[str, Any]]

Async (AsyncValyu)

AsyncValyu.search takes the same arguments and returns the same SearchResponse - the only difference is you await it. The common reason to use it is running several queries in parallel:

import asyncio
from valyu import AsyncValyu

queries = ["DCF terminal value", "Black-Scholes pricing", "GARCH volatility"]

async def main():
    async with AsyncValyu() as valyu:
        responses = await asyncio.gather(*[
            valyu.search(q, max_num_results=10) for q in queries
        ])
        for q, r in zip(queries, responses):
            print(q, len(r.results))

asyncio.run(main())

Wall time is the slowest query, not the sum. For hundreds of queries, cap concurrency with an asyncio.Semaphore - see the Python SDK overview for constructor options and lifecycle patterns.

Source types

Web - general websites, news, blogs, forums, documentation.
Proprietary - valyu/valyu-arxiv (arXiv papers), valyu/valyu-pubmed (medical literature), valyu/valyu-stocks (market data), and many more.

Browse the full catalog on the Valyu Platform.

​Basic usage

​Common patterns

​Reference

​Source types

Basic usage

Common patterns

Reference

Source types