curl --request POST \
--url https://api.valyu.ai/v1/search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "latest developments in quantum computing",
"max_num_results": 5
}
'{
"success": true,
"error": null,
"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 that reduces qubit errors by 99.9%...",
"description": "Major breakthrough in quantum error correction methodology",
"source": "web",
"price": 0.0015,
"length": 15420,
"image_url": null,
"relevance_score": 0.95,
"data_type": "unstructured",
"source_type": "website",
"publication_date": "2024-06-15"
},
{
"id": "valyu/valyu-arxiv/2401.12345",
"title": "Advances in Topological Quantum Computing",
"url": "https://arxiv.org/abs/2401.12345",
"content": "We present a novel approach to topological quantum error correction...",
"description": "Topological approaches to fault-tolerant quantum computation",
"source": "valyu/valyu-arxiv",
"price": 0.0005,
"length": 28000,
"image_url": null,
"relevance_score": 0.89,
"data_type": "unstructured",
"source_type": "paper",
"publication_date": "2024-01-15",
"doi": "10.48550/arXiv.2401.12345",
"authors": [
"J. Smith",
"A. Chen",
"M. Kumar"
]
}
],
"results_by_source": {
"web": 3,
"proprietary": 2
},
"total_deduction_dollars": 0.0075,
"total_characters": 45230
}Search
Reference for the Valyu Search endpoint to search the web, research, and proprietary datasets via POST /v1/search.
curl --request POST \
--url https://api.valyu.ai/v1/search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "latest developments in quantum computing",
"max_num_results": 5
}
'{
"success": true,
"error": null,
"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 that reduces qubit errors by 99.9%...",
"description": "Major breakthrough in quantum error correction methodology",
"source": "web",
"price": 0.0015,
"length": 15420,
"image_url": null,
"relevance_score": 0.95,
"data_type": "unstructured",
"source_type": "website",
"publication_date": "2024-06-15"
},
{
"id": "valyu/valyu-arxiv/2401.12345",
"title": "Advances in Topological Quantum Computing",
"url": "https://arxiv.org/abs/2401.12345",
"content": "We present a novel approach to topological quantum error correction...",
"description": "Topological approaches to fault-tolerant quantum computation",
"source": "valyu/valyu-arxiv",
"price": 0.0005,
"length": 28000,
"image_url": null,
"relevance_score": 0.89,
"data_type": "unstructured",
"source_type": "paper",
"publication_date": "2024-01-15",
"doi": "10.48550/arXiv.2401.12345",
"authors": [
"J. Smith",
"A. Chen",
"M. Kumar"
]
}
],
"results_by_source": {
"web": 3,
"proprietary": 2
},
"total_deduction_dollars": 0.0075,
"total_characters": 45230
}Wire the Valyu Search endpoint into an agent or app, with sensible defaults and parameter guidance.
Authorizations
API key for authentication. Get yours at platform.valyu.ai.
Body
Search request parameters.
The search query to execute. Supports natural language queries.
"latest developments in quantum computing"
Maximum number of results to return. Higher limits (up to 100) available on request.
1 <= x <= 2010
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.
all, web, proprietary, news "all"
Maximum budget in CPM (cost per mille/thousand tokens). When not set, automatically calculated based on max_num_results and search_type.
x > 020
Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out.
0 <= x <= 10.5
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).
["valyu/valyu-arxiv", "valyu/valyu-pubmed"]
Sources to exclude from the search. Same format as included_sources except presets are not supported.
["reddit.com"]
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.
Show child attributes
Show child attributes
{
"nasa.gov": 5,
"noaa.gov": 3,
"nih.gov": 1,
"example.com": -4
}
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.
500"Focus on oncology clinical trials from 2023 onwards"
Deprecated. Use instructions instead. Falls back to this value if instructions is not set.
500Indicates whether this request originates from an AI tool call. Affects query rewriting behavior.
Controls the maximum character length of content per result.
"short"- 25,000 characters (default)"medium"- 50,000 characters"large"- 100,000 characters"max"- No limit- Any positive integer for a custom character limit
short, medium, large, max "short"
Filter results published on or after this date. Format: YYYY-MM-DD. If set without end_date, defaults to today.
"2024-01-01"
Filter results published on or before this date. Format: YYYY-MM-DD. If set without start_date, defaults to 1900-01-01.
"2024-12-31"
ISO 3166-1 alpha-2 country code for geo-targeted web search results.
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 "US"
Bypass LLM query rewriting and reranking for lower latency. Forces web-only search. Cannot be used with search_type: "proprietary".
Return only URLs without full content extraction. Only available when search_type is "web" or "news". Skips reranking.
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.
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.
off, prefer, only 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.
Response
Search completed successfully with results.
Search response containing results and metadata.
Whether the search completed successfully.
true
Transaction ID for tracking and support.
"tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
The original query as submitted.
"latest developments in quantum computing"
Search results ordered by relevance.
Show child attributes
Show child attributes
Count of results broken down by source type.
Show child attributes
Show child attributes
{ "web": 5, "proprietary": 3 }
Total cost charged for this search in USD.
0.0075
Sum of all result content lengths in characters.
45230
Error or warning message. May be non-empty even on successful responses if some sources had issues.
null
Warning messages, if any (e.g. collection resolution warnings). Only present when warnings exist.
Was this page helpful?