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

Wire up Valyu Search with the Python SDK.

Open in Cursor

​
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"])

# 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

query (str, required) - the search query. See the Prompting Guide.
ParameterTypeDescriptionDefault
search_type"web" | "proprietary" | "all" | "news"Which sources to search"all"
max_num_resultsintResults to return (1-20, up to 100 with the increased_max_results permission)10
max_pricefloatMax cost per thousand retrievals (CPM). When omitted, all sources are searched regardless of costNone
is_tool_callboolTrue for AI agents/tools, False for direct user queriesTrue
relevance_thresholdfloatMinimum relevance score (0.0-1.0)0.5
included_sourcesList[str]Sources to search within (dataset ids, domains, or presets)None
excluded_sourcesList[str]Sources to excludeNone
source_biasesDict[str, int]Bias ranking per source (-5 to +5) without hard filteringNone
instructionsstrNatural-language instructions to rank by intent. Ignored in fast modeNone
categorystrDeprecated. Use instructionsNone
start_date / end_datestrDate filter (YYYY-MM-DD)None
country_codestr2-letter ISO country code to bias resultsNone
response_lengthstr | int"short" (25k), "medium" (50k), "large" (100k), "max" (full), or a custom character count"short"
fast_modeboolReduced latency, shorter resultsFalse
url_onlyboolReturn URLs only (no content). Applies when search_type is "web" or "news"False
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]
    authors: Optional[List[str]]
    citation: Optional[str]
    citation_count: Optional[int]
    doi: Optional[str]
    references: Optional[str]
    metadata: Optional[Dict[str, Any]]
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.