> ## 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 from the Valyu Search API.

## Multi-Step Search Workflows

For complex research tasks, break your search into multiple steps rather than relying on a single query. This works especially well for technical domains like research, finance, and medicine.

**Example workflow**:

<CodeGroup>
  ```python Python theme={null}
  # Multi-step search workflow
  async def research_agent(query: str):
      # Step 1: Break down the query into focused searches
      sub_queries = decompose_query(query)

      results = {}
      for i, sub_query in enumerate(sub_queries):
          # Step 2: Adjust strategy based on what you've found
          strategy = adapt_strategy(sub_query, results)

          search_result = valyu.search(
              query=sub_query,
              included_sources=strategy.sources,
              max_price=strategy.budget,
              relevance_threshold=0.65
          )
          results[f"step_{i}"] = search_result

          # Step 3: Fill in any gaps
          gaps = identify_knowledge_gaps(search_result, query)
          if gaps:
              gap_result = valyu.search(
                  query=gaps[0].refined_query,
                  included_sources=gaps[0].target_sources,
                  max_price=50.0
              )
              results[f"gap_fill_{i}"] = gap_result

      # Step 4: Combine everything
      return synthesise_multi_source_findings(results)

  ```

  ```javascript JavaScript theme={null}
  // Multi-step search workflow
  async function researchAgent(query) {
      // Step 1: Break down the query into focused searches
      const subQueries = decomposeQuery(query);

      const results = {};
      for (let i = 0; i < subQueries.length; i++) {
          const subQuery = subQueries[i];

          // Step 2: Adjust strategy based on what you've found
          const strategy = adaptStrategy(subQuery, results);

          const searchResult = await valyu.search(subQuery, {
              includedSources: strategy.sources,
              maxPrice: strategy.budget,
              relevanceThreshold: 0.65
          });
          results[`step_${i}`] = searchResult;

          // Step 3: Fill in any gaps
          const gaps = identifyKnowledgeGaps(searchResult, query);
          if (gaps && gaps.length > 0) {
              const gapResult = await valyu.search(gaps[0].refined_query, {
                  includedSources: gaps[0].target_sources,
                  maxPrice: 50.0
              });
              results[`gap_fill_${i}`] = gapResult;
          }
      }

      // Step 4: Combine everything
      return synthesiseMultiSourceFindings(results);
  }
  ```
</CodeGroup>

## AI vs Human Searches

Valyu is optimised for AI agents by default. The `tool_call_mode` parameter controls this:

**For AI agents** (the default):

<CodeGroup>
  ```python Python theme={null}
  # Optimised for LLMs
  response = valyu.search(
      "quantum error correction surface codes LDPC performance benchmarks",
      tool_call_mode=True,  # Default
  )
  ```

  ```javascript JavaScript theme={null}
  // Optimised for LLMs
  const response = await valyu.search(
    "quantum error correction surface codes LDPC performance benchmarks",
    {
      toolCallMode: true, // Default
    }
  );
  ```
</CodeGroup>

**For human-facing searches**:

<CodeGroup>
  ```python Python theme={null}
  # Better for human readability
  response = valyu.search(
      "quantum computing error correction methods",
      tool_call_mode=False,
  )
  ```

  ```javascript JavaScript theme={null}
  // Better for human readability
  const response = await valyu.search(
    "quantum computing error correction methods",
    {
      toolCallMode: false,
    }
  );
  ```
</CodeGroup>

## Using Search Parameters

Combine [good prompts](/search/prompting) with search parameters:

<CodeGroup>
  ```python Python theme={null}
  response = valyu.search(
      "GPT-4 vs GPT-3 architectural innovations: training efficiency, inference optimisation, and benchmark comparisons",
      search_type="proprietary",
      max_num_results=10,
      relevance_threshold=0.6,
      included_sources=["valyu/valyu-arxiv"],
      max_price=50.0,
      category="machine learning",
      start_date="2024-01-01",
      end_date="2024-12-31"
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await valyu.search(
    "GPT-4 vs GPT-3 architectural innovations: training efficiency, inference optimisation, and benchmark comparisons",
    {
      searchType: "proprietary",
      maxNumResults: 10,
      relevanceThreshold: 0.6,
      includedSources: ["valyu/valyu-arxiv"],
      maxPrice: 50.0,
      category: "machine learning",
      startDate: "2024-01-01",
      endDate: "2024-12-31",
    }
  );
  ```
</CodeGroup>

<Tip>
  Use `included_sources` to search datasets other APIs can't access—like
  `valyu/valyu-arxiv` for academic papers or [specialised
  datasets](https://platform.valyu.ai/data-sources) for financial data.
</Tip>

## Balancing Quality and Cost

### Budget Tiers

Not getting enough results? Try increasing `max_price`:

<CodeGroup>
  ```python Python theme={null}
  search_configs = [
      {"max_price": 20.0, "use_case": "Quick fact-checking"},
      {"max_price": 50.0, "use_case": "Standard research"},
      {"max_price": 100.0, "use_case": "Comprehensive analysis"},
  ]
  ```

  ```javascript JavaScript theme={null}
  const searchConfigs = [
    { maxPrice: 20.0, useCase: "Quick fact-checking" },
    { maxPrice: 50.0, useCase: "Standard research" },
    { maxPrice: 100.0, useCase: "Comprehensive analysis" },
  ];
  ```
</CodeGroup>

**What each budget gets you**:

* **\$20 CPM**: Basic web + academic content
* **\$50 CPM**: Full web + most research databases + financial data
* **\$100 CPM**: Premium sources + financial data + specialised datasets

<Tip>
  Higher budgets unlock [exclusive sources](https://platform.valyu.ai/data-sources)
  like academic journals, financial data feeds, and curated research databases.
</Tip>

### Managing Context Size

Control how much data goes into your LLM's context window:

<CodeGroup>
  ```python Python theme={null}
  # Smaller context
  lightweight_search = valyu.search(
      "transformer architecture innovations",
      max_num_results=3,
      results_length="short",
      max_price=50.0
  )

  # Larger context
  comprehensive_search = valyu.search(
      "transformer architecture innovations",
      max_num_results=15,
      results_length="max",
      max_price=100.0
  )

  ```

  ```javascript JavaScript theme={null}
  // Smaller context
  const lightweightSearch = await valyu.search(
      "transformer architecture innovations",
      {
          maxNumResults: 3,
          resultsLength: "short",
          maxPrice: 50.0
      }
  );

  // Larger context
  const comprehensiveSearch = await valyu.search(
      "transformer architecture innovations",
      {
          maxNumResults: 15,
          resultsLength: "long",
          maxPrice: 100.0
      }
  );
  ```
</CodeGroup>

**Token estimates**:

* **Short**: \~6k tokens per result (25k chars)
* **Medium**: \~12k tokens per result (50k chars)
* **Long**: \~24k tokens per result (100k chars)
* **Rule of thumb**: 4 characters ≈ 1 token

<Tip>
  Start with `max_num_results=10` and `results_length="short"`, then adjust
  based on your needs.
</Tip>

## Specialised Datasets

Valyu offers datasets beyond standard web search. Browse them at [platform.valyu.ai/data-sources](https://platform.valyu.ai/data-sources).

**Categories include**:

* **Academic**: ArXiv, PubMed, academic publishers
* **Financial**: SEC filings, earnings reports, market data
* **Medical**: Clinical trials, FDA drug labels, medical literature
* **Technical**: Patents, specifications, implementation guides
* **Books & Literature**: Digitised texts, reference materials

**Targeting specific datasets**:

<CodeGroup>
  ```python Python theme={null}
  # Academic search
  academic_search = valyu.search(
      "CRISPR gene editing clinical trials safety outcomes",
      included_sources=["valyu/valyu-pubmed", "valyu/valyu-US-clinical-trials"],
      max_price=30.0
  )

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

  ```

  ```javascript JavaScript theme={null}
  // Academic search
  const academicSearch = await valyu.search(
      "CRISPR gene editing clinical trials safety outcomes",
      {
          includedSources: ["valyu/valyu-pubmed", "valyu/valyu-US-clinical-trials"],
          maxPrice: 30.0
      }
  );

  // Financial search
  const financialSearch = await valyu.search(
      "Tesla Q3 2024 earnings revenue breakdown",
      {
          includedSources: ["valyu/valyu-US-sec-filings", "valyu/valyu-US-earnings"],
          maxPrice: 60.0
      }
  );
  ```
</CodeGroup>

<Tip>
  **Data advantage**: **Proprietary datasets** behind the Search API often
  contain information unavailable through standard web APIs, giving your AI
  system access to **authoritative, structured knowledge** that improves factual
  accuracy.
</Tip>

## Common Mistakes to Avoid

1. **Wasting tokens**: Use `max_num_results` and `results_length` to control context size
2. **Skipping filters**: Set relevance thresholds and source controls
3. **Ignoring costs**: Balance `max_price` with your quality needs
4. **Wrong sources**: Pick datasets that match your domain—academic, financial, medical, or web
5. **Single-shot queries**: For complex research, use multi-step workflows

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Integration" icon="code" href="/quickstart">
    Get your first Valyu search running in minutes
  </Card>

  <Card title="API Reference" icon="lightbulb" href="/api-reference/endpoint/deepsearch">
    Explore all search parameters and response formats
  </Card>
</CardGroup>

## Get Help

* **Technical Support**: [contact@valyu.ai](mailto:contact@valyu.ai)
* **Developer Community**: [Join our Discord](https://discord.gg/umtmSsppRY)