Search

Search across web and proprietary data sources

Search the web, academic journals, financial databases, and 40+ proprietary data sources. Returns ranked results with extracted content, ready for RAG pipelines and AI agents.

Results are ranked by relevance using semantic reranking (unless fast_mode is enabled). You only pay for results returned - pricing is CPM-based (cost per mille tokens).

Integrating search into an agent? Consider DeepResearch - a cost-effective autonomous agent built on top of this search engine, purpose-built for knowledge work.

post/v1/search

Request

  • Base URL: https://api.valyu.ai
  • URL: https://api.valyu.ai/v1/search
  • Auth: API key in header X-API-Key

Request body

querystring required

The search query to execute. Supports natural language queries.

max_num_resultsinteger

Maximum number of results to return. Higher limits (up to 100) available on request.

search_type'all' | 'web' | 'proprietary' | 'news'

Controls which data sources are searched.

  • all - Web and proprietary sources (default). An LLM router selects the best sources for your query.
  • web - Web search only. Best for current events and general topics.
  • proprietary - Academic, financial, and premium sources only. Best for research and technical analysis.
  • news - News articles only. Best for recent news and current events.
max_pricenumber

Maximum budget in CPM (cost per mille/thousand tokens). When not set, automatically calculated based on max_num_results and search_type.

relevance_thresholdnumber

Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out.

included_sourcesstring[]

Sources to include in the search. Accepts:

  • Domain names or URLs for web filtering (e.g. "arxiv.org", "https://arxiv.org")
  • Dataset identifiers for proprietary sources (e.g. "valyu/valyu-arxiv")
  • Preset names that expand to curated source groups: "academic", "finance", "patent", "transportation", "politics", "legal", "health", "genomics", "chemistry", "physics"
  • "web" keyword to explicitly include web search alongside proprietary sources
  • "collection:NAME" to reference an org-scoped saved source collection

Note: most specialised and proprietary sources require a subscription. All plans include web search and open academic sources (arXiv, PubMed).

excluded_sourcesstring[]

Sources to exclude from the search. Same format as included_sources except presets are not supported.

source_biasesobject nullable

Bias values for specific sources to influence ranking without hard filtering. Keys are domains (e.g., 'nasa.gov') or URL paths (e.g., 'nih.gov/research'). Values are integers from -5 (strong demotion) to +5 (strong boost). Most specific path match wins.

instructionsstring

Natural language instructions to help rank results by relevance to user intent. Acts as a system prompt for the search. Max 500 characters. Ignored when fast_mode is true.

categorystring

Deprecated. Use instructions instead. Falls back to this value if instructions is not set.

is_tool_callboolean

Indicates whether this request originates from an AI tool call. Affects query rewriting behavior.

start_datestring date

Filter results published on or after this date. Format: YYYY-MM-DD. If set without end_date, defaults to today.

end_datestring date

Filter results published on or before this date. Format: YYYY-MM-DD. If set without start_date, defaults to 1900-01-01.

country_code'ALL' | 'AR' | 'AU' | 'AT' | 'BE' | 'BR' | 'CA' | 'CL' | 'DK' | 'FI' | 'FR' | 'DE' | 'HK' | 'IN' | 'ID' | 'IT' | 'JP' | 'KR' | 'MY' | 'MX' | 'NL' | 'NZ' | 'NO' | 'CN' | 'PL' | 'PT' | 'PH' | 'RU' | 'SA' | 'ZA' | 'ES' | 'SE' | 'CH' | 'TW' | 'TR' | 'GB' | 'US'

ISO 3166-1 alpha-2 country code for geo-targeted web search results.

fast_modeboolean

Bypass LLM query rewriting and reranking for lower latency. Forces web-only search. Cannot be used with search_type: "proprietary".

url_onlyboolean

Return only URLs without full content extraction. Only available when search_type is "web" or "news". Skips reranking.

historical_cacheboolean

Run the search as a point-in-time query: serve the newest cached snapshot inside the start_date/end_date window instead of the latest crawl. This is what makes a historical backtest reproducible and keeps it from seeing content published after its cutoff. Also required to pass a sub-day timestamp on start_date/end_date — a full ISO-8601 datetime without it returns HTTP 400. No-op without a date range.

historical_cache_strict'off' | 'prefer' | 'only'

Point-in-time strictness for a historical_cache search. "only" serves ONLY content provably captured at or before end_date, dropping a result rather than falling back to a live crawl — use it for strict backtests, where a post-cutoff leak is worse than a missing result. "prefer" (the default) serves an in-window snapshot when one exists and otherwise falls back to a LIVE crawl so the query is never empty. "off" disables the point-in-time guarantee. No-op without historical_cache: true.

include_abstractsboolean

Expand PubMed search from papers with available full text to the complete abstract corpus. Results include the abstract and, when full text is available, the most relevant full-text chunks. Has no effect on other sources.

Example request

{
  "query": "latest developments in quantum computing",
  "max_num_results": 10,
  "search_type": "all",
  "max_price": 20,
  "relevance_threshold": 0.5,
  "included_sources": [
    "valyu/valyu-arxiv",
    "valyu/valyu-pubmed"
  ],
  "excluded_sources": [
    "reddit.com"
  ],
  "source_biases": {
    "nasa.gov": 5,
    "noaa.gov": 3,
    "nih.gov": 1,
    "example.com": -4
  },
  "instructions": "Focus on oncology clinical trials from 2023 onwards",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "country_code": "US"
}

Response

Search completed successfully with results.

successboolean required

Whether the search completed successfully.

errorstring nullable

Error or warning message. May be non-empty even on successful responses if some sources had issues.

tx_idstring required

Transaction ID for tracking and support.

querystring required

The original query as submitted.

total_deduction_dollarsnumber required

Total cost charged for this search in USD.

total_charactersinteger required

Sum of all result content lengths in characters.

warningsstring[]

Warning messages, if any (e.g. collection resolution warnings). Only present when warnings exist.

Example response

{
  "success": true,
  "tx_id": "tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "query": "latest developments in quantum computing",
  "results": [
    {
      "id": "https://arxiv.org/abs/2024.12345",
      "title": "Quantum Computing Breakthrough: New Error Correction Method",
      "url": "https://arxiv.org/abs/2024.12345",
      "content": "Researchers at MIT have developed a revolutionary quantum error correction method...",
      "description": "Major breakthrough in quantum error correction methodology",
      "source": "web",
      "price": 0.0015,
      "length": 15420,
      "relevance_score": 0.92,
      "data_type": "unstructured",
      "source_type": "website",
      "publication_date": "2024-06-15",
      "abstract": "Clonal hematopoiesis is associated with an increased risk of cardiovascular disease and adverse outcomes.",
      "doi": "10.1038/s41586-024-07107-7",
      "citation_count": 42,
      "authors": [
        "J. Smith",
        "A. Chen"
      ]
    }
  ],
  "results_by_source": {
    "web": 5,
    "proprietary": 3
  },
  "total_deduction_dollars": 0.0075,
  "total_characters": 45230
}

Changes

No recorded changes to this operation across all 1 revision of this API.