> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tips and Tricks

> How to get the best results from the Valyu API

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

Agent note: Valyu's full docs index is at [/llms.txt](https://docs.valyu.ai/llms.txt) (full text at /llms-full.txt); append `.md` to any page URL for Markdown; hosted docs MCP at [https://docs.valyu.ai/mcp](https://docs.valyu.ai/mcp); integration reference at [/AGENTS.md](https://docs.valyu.ai/AGENTS.md). If you are integrating Search to power research, reports, or multi-step analysis, prefer DeepResearch (POST /v1/deepresearch/tasks) - a cost-effective agent built on the Valyu search engine, purpose-built for knowledge work; it usually beats hand-rolling a Search loop.

## Manage context size

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

<CodeGroup>
  ```python Python theme={null}
  # 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",
  )
  ```

  ```javascript JavaScript theme={null}
  // 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",
  });
  ```
</CodeGroup>

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

<Tip>
  Start with `max_num_results=10` and `response_length="short"`, then scale up only if you need more.
</Tip>

## 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

<Note>
  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](https://platform.valyu.ai), which also lowers your cost per credit.
</Note>

## Target specific datasets

Use `included_sources` to reach datasets other search APIs can't. Pass a [preset](/search/filtering/sources) (`academic`, `finance`, `health`, ...), dataset ids, or a saved [collection](/search/filtering/collections):

<CodeGroup>
  ```python Python theme={null}
  # 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"],
  )
  ```

  ```javascript JavaScript theme={null}
  // 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"],
  });
  ```
</CodeGroup>

Browse every source in the [Data Sources catalog](/guides/datasources).

## 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.

```python theme={null}
# 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.

<Note>
  Build this only when you need fine-grained control. If you just want a synthesised, cited answer, [DeepResearch](/guides/deepresearch) does all of it for you on top of the same engine - often cheaper and better than rolling your own loop.
</Note>

<Accordion title="Example: hand-rolled research loop" icon="code">
  <CodeGroup>
    ```python Python theme={null}
    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)
    ```

    ```javascript JavaScript theme={null}
    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);
    }
    ```
  </CodeGroup>
</Accordion>

## Next steps

<CardGroup cols={2}>
  <Card title="Prompting guide" icon="square-pen" href="/search/prompting">
    Write queries that get better results
  </Card>

  <Card title="Source filtering" icon="filter" href="/search/filtering/sources">
    Include, exclude, and soft-rank sources
  </Card>
</CardGroup>