Skip to main content
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: 
# 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",
)

// Lightweight: small context
await valyu.search("transformer architecture innovations", {
  maxNumResults: 3,
  responseLength: "short",
});

// Comprehensive: large context
await valyu.search("transformer architecture innovations", {
  maxNumResults: 15,
  responseLength: "large",
});
Token estimates (rule of thumb: 4 characters ≈ 1 token):
  • short - ~6k tokens / result (25k chars)
  • medium - ~12k tokens / result (50k chars)
  • large - ~24k tokens / result (100k chars)
Start with max_num_results=10 and response_length="short", then scale up only if you need more.

​
Control cost with max_price

max_price sets a CPM (cost per 1,000 results) ceiling. Raise it when you’re not getting enough results from premium sources:
  • $20 CPM - basic web + academic content
  • $50 CPM - full web + most research databases + financial data
  • $100 CPM - premium sources + specialised datasets
Web search and open academic sources (arXiv, PubMed) are available on every plan, including free signup credits. Premium and proprietary sources - SEC filings, patents, drug discovery, genomics, advanced financials - need a subscription, which also lowers your cost per credit.

​
Target specific datasets

Use included_sources to reach datasets other search APIs can’t. Pass a preset (academic, finance, health, …), dataset ids, or a saved collection: 
# Academic
valyu.search(
    "CRISPR gene editing clinical trials safety outcomes",
    included_sources=["valyu/valyu-pubmed", "valyu/valyu-clinical-trials"],
)

# Financial
valyu.search(
    "Tesla Q3 2024 earnings revenue breakdown",
    included_sources=["valyu/valyu-sec-filings", "valyu/valyu-earnings-US"],
)

// Academic
await valyu.search("CRISPR gene editing clinical trials safety outcomes", {
  includedSources: ["valyu/valyu-pubmed", "valyu/valyu-clinical-trials"],
});

// Financial
await valyu.search("Tesla Q3 2024 earnings revenue breakdown", {
  includedSources: ["valyu/valyu-sec-filings", "valyu/valyu-earnings-US"],
});
Browse every source in the Data Sources catalog.

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

​
Multi-step research

For complex tasks, break the work into multiple searches: decompose the question, search each part, fill gaps, then synthesise.
Build this only when you need fine-grained control. If you just want a synthesised, cited answer, DeepResearch does all of it for you on top of the same engine - often cheaper and better than rolling your own loop.
async def research_agent(query: str):
    sub_queries = decompose_query(query)
    results = {}
    for i, sub_query in enumerate(sub_queries):
        strategy = adapt_strategy(sub_query, results)
        results[f"step_{i}"] = valyu.search(
            query=sub_query,
            included_sources=strategy.sources,
            max_price=strategy.budget,
            relevance_threshold=0.65,
        )
        gaps = identify_knowledge_gaps(results[f"step_{i}"], query)
        if gaps:
            results[f"gap_fill_{i}"] = valyu.search(
                query=gaps[0].refined_query,
                included_sources=gaps[0].target_sources,
                max_price=50.0,
            )
    return synthesise_multi_source_findings(results)

async function researchAgent(query) {
  const subQueries = decomposeQuery(query);
  const results = {};
  for (let i = 0; i < subQueries.length; i++) {
    const strategy = adaptStrategy(subQueries[i], results);
    results[`step_${i}`] = await valyu.search(subQueries[i], {
      includedSources: strategy.sources,
      maxPrice: strategy.budget,
      relevanceThreshold: 0.65,
    });
    const gaps = identifyKnowledgeGaps(results[`step_${i}`], query);
    if (gaps?.length) {
      results[`gap_fill_${i}`] = await valyu.search(gaps[0].refined_query, {
        includedSources: gaps[0].target_sources,
        maxPrice: 50.0,
      });
    }
  }
  return synthesiseMultiSourceFindings(results);
}

​
Next steps

Prompting guide

Write queries that get better results

Source filtering

Include, exclude, and soft-rank sources