Tips and Tricks

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.

Example: hand-rolled research 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);
}

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Compare

Account & Pricing

Other

Tips and Tricks

Manage context size

Control cost with max_price

Target specific datasets

AI vs human searches

Multi-step research

Next steps

Prompting guide

Source filtering

​Manage context size

​Control cost with max_price

​Target specific datasets

​AI vs human searches

​Multi-step research

​Next steps

Prompting guide

Source filtering

Manage context size

Control cost with max_price

Target specific datasets

AI vs human searches

Multi-step research

Next steps