Tune results and cost

Tune Valyu Search: control context size with max_num_results and response_length, track cost per request, target datasets and diagnose missing results.

Practical tips for getting better results and controlling cost on the Valyu Search API.

Manage context size

Control how much data lands in your LLM’s context window with max_num_results and response_length:

Python

# Lightweight: small context
valyu.search(
    "transformer architecture innovations",
    max_num_results=3,
    response_length="short",
)

# Comprehensive: large context
valyu.search(
    "transformer architecture innovations",
    max_num_results=15,
    response_length="large",
)

Maximum content sizes (token counts below are rough estimates, not guaranteed sizes):

• short - ~6k tokens / result (25k chars)
• medium - ~12k tokens / result (50k chars)
• large - ~24k tokens / result (100k chars)

Start with max_num_results=5 and response_length="short", then scale up only if you need more.

Track cost separately from context size

Record total_deduction_dollars for each request. response_length controls the maximum content returned per result; it is not a cost budget. Source choice and result count also affect the request.

Each result uses credits from your balance, and each result’s charge is in results[].price:

Results from	Credits per result
Web and news	0.1
arXiv, PubMed, bioRxiv, medRxiv	0.05
Other datasets	Listed in the data sources catalogue

max_price caps the cost of the whole request, not each result. Result selection can return fewer items to fit the cap, and a cap too low for the requested result count fails with 400. Dataset prices (pricing.cpm) are each source’s price per 1,000 returned results. See pricing and the request reference. Confirm source-specific behavior for licensed collections, and enforce a separate total budget across all calls in your application.

Target specific datasets

Choose source filters for datasets, domains or presets. Save recurring selections as collections. The source discovery guide explains how to find current IDs and supported APIs.

AI vs human searches

Valyu is optimised for AI agents by default (is_tool_call=true). Set it to false for human-facing UIs to get more readable results.

# AI agent (default) - optimised for LLM consumption
valyu.search("quantum error correction surface codes benchmarks", is_tool_call=True)

# Human-facing - optimised for readability
valyu.search("quantum computing error correction methods", is_tool_call=False)

Diagnose missing results

Check the response’s success and error fields first. Then test one variable at a time: broaden the date range, remove an unnecessary source filter or site: term, or reduce the relevance threshold. A site: term in the query filters every result, including dataset results, so it can leave nothing to return. Confirm the dataset supports Search and your organization has access in the source catalogue.

Do not silently replace a failed specialist search with general web results when the user explicitly requested that dataset. Make the change visible in your application.

Next steps

Prompting guide

Write queries that get better results

Source filtering

Include, exclude, and soft-rank sources