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

# Search Quickstart

> Search across web, research, and financial data sources

Search across web content, academic journals, financial data, and proprietary datasets. The Search API returns results ready for RAG pipelines, AI agents, and applications.

## What You Can Do

* **Search everything** - Web, research journals, books, and live financial data in one call
* **Get real-time results** - Up-to-the-minute information from all sources
* **Filter precisely** - Control sources, dates, relevance scores, and result count
* **Feed your AI** - Results formatted for LLM context windows

## Features

<CardGroup cols={2}>
  <Card title="Multi-Source Search" icon="globe" href="#basic-search">
    Search web, research papers, books, and financial data in one API call.
  </Card>

  <Card title="AI Ready" icon="book-open" href="#ai-agent-vs-user-queries">
    Results go straight into your AI's context window.
  </Card>

  <Card title="Source Control" icon="filter" href="/search/filtering/sources">
    Include or exclude specific domains, URLs, and datasets.
  </Card>

  <Card title="Date Filtering" icon="calendar-days" href="/search/filtering/date">
    Filter by publication date for recent or historical content.
  </Card>
</CardGroup>

## Getting Started

### Basic Search

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu() # Uses VALYU_API_KEY from env

  response = valyu.search(
      query="latest developments in quantum computing",
      max_num_results=5,
      search_type="all",
  )

  for result in response["results"]:
      print(f"Title: {result['title']}")
      print(f"URL: {result['url']}")
      print(f"Source: {result['source_type']}")
      print(f"Content: {result['content'][:200]}...")
      print("---")

  ```

  ```javascript JavaScript theme={null}
  import { Valyu } from "valyu-js";

  const valyu = new Valyu(); // Uses VALYU_API_KEY from env

  const response = await valyu.search({
    query: "latest developments in quantum computing",
    maxNumResults: 5,
    searchType: "all",
  });

  response.results.forEach(result => {
    console.log(`Title: ${result.title}`);
    console.log(`URL: ${result.url}`);
    console.log(`Source: ${result.sourceType}`);
    console.log(`Content: ${result.content.substring(0, 200)}...`);
    console.log("---");
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "latest developments in quantum computing",
      "max_num_results": 5,
      "search_type": "all"
    }'
  ```
</CodeGroup>

### Fast Mode

Use fast mode for quicker responses with shorter results. Good for general queries:

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()

  response = valyu.search(
      query="latest market trends in tech stocks",
      fast_mode=True,
      max_num_results=5,
      search_type="all",
  )

  for result in response["results"]:
      print(f"Title: {result['title']}")
      print(f"Source: {result['source_type']}")
      print(f"Content: {result['content'][:200]}...")
      print("---")

  ```

  ```javascript JavaScript theme={null}
  import { Valyu } from "valyu-js";

  const valyu = new Valyu();

  const response = await valyu.search({
    query: "latest market trends in tech stocks",
    fastMode: true,
    maxNumResults: 5,
    searchType: "all",
  });

  response.results.forEach(result => {
    console.log(`Title: ${result.title}`);
    console.log(`Source: ${result.sourceType}`);
    console.log(`Content: ${result.content.substring(0, 200)}...`);
    console.log("---");
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "latest market trends in tech stocks",
      "fast_mode": true,
      "max_num_results": 5,
      "search_type": "all"
    }'
  ```
</CodeGroup>

### Search Types

| **Type**      | **What it searches**                     | **Use for**                    |
| ------------- | ---------------------------------------- | ------------------------------ |
| `all`         | Web and proprietary sources (default)    | Comprehensive coverage         |
| `web`         | Web only                                 | Current events, general topics |
| `proprietary` | Research, financial, and premium sources | Research, technical analysis   |
| `news`        | News articles only                       | Current news and journalism    |

## Advanced Features

### AI Agent vs User Queries

Set `is_tool_call` based on who's making the request:

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()

  # AI agent making a tool call
  agent_response = valyu.search(
      query="latest AI research papers",
      is_tool_call=True,  # Optimised for AI
      max_num_results=10,
  )

  # User query
  user_response = valyu.search(
      query="explain quantum computing basics",
      is_tool_call=False,  # Optimised for humans
      max_num_results=5,
  )

  ```

  ```javascript JavaScript theme={null}
  import { Valyu } from "valyu-js";

  const valyu = new Valyu();

  // AI agent making a tool call
  const agentResponse = await valyu.search({
    query: "latest AI research papers",
    isToolCall: true, // Optimised for AI
    maxNumResults: 10,
  });

  // User query
  const userResponse = await valyu.search({
    query: "explain quantum computing basics",
    isToolCall: false, // Optimised for humans
    maxNumResults: 5,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "latest AI research papers",
      "is_tool_call": true,
      "max_num_results": 10
    }'
  ```
</CodeGroup>

### Response Length

Control how much content comes back per result:

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()

  # Short snippets
  response = valyu.search(
      query="renewable energy trends",
      response_length="short",
      max_num_results=10,
  )

  # Full content
  response = valyu.search(
      query="financial market analysis",
      response_length="max",
      max_num_results=3,
  )

  # Custom limit
  response = valyu.search(
      query="technical documentation",
      response_length=5000,  # Exactly 5000 characters
      max_num_results=5,
  )

  ```

  ```javascript JavaScript theme={null}
  import { Valyu } from "valyu-js";

  const valyu = new Valyu();

  // Short snippets
  const response = await valyu.search({
    query: "renewable energy trends",
    responseLength: "short",
    maxNumResults: 10,
  });

  // Full content
  const response2 = await valyu.search({
    query: "financial market analysis",
    responseLength: "max",
    maxNumResults: 3,
  });

  // Custom limit
  const response3 = await valyu.search({
    query: "technical documentation",
    responseLength: 5000,
    maxNumResults: 5,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "renewable energy trends",
      "response_length": "short",
      "max_num_results": 10
    }'
  ```
</CodeGroup>

**Options:**

* `"short"`: \~25,000 characters per result
* `"medium"`: \~50,000 characters per result
* `"large"`: \~100,000 characters per result
* `"max"`: Full content
* Custom integer: Exact character count

### 100 Results

The Search API supports up to 100 results per query. This requires the `increased_max_results` permission on your API key.

**To enable 100 results:**

1. Go to [API Key Management](http://platform.valyu.ai/user/account/apikeys?req=increase_results)
2. Request the `increased_max_results` permission
3. Create a new API key after approval

<Note>
  Without this permission, the default maximum is 20 results per query.
</Note>

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()  # Use API key with increased_max_results permission

  response = valyu.search(
      query="renewable energy innovations 2025",
      max_num_results=100,  # Requires increased_max_results permission
  )

  print(f"Retrieved {len(response['results'])} results")
  ```

  ```javascript JavaScript theme={null}
  import { Valyu } from "valyu-js";

  const valyu = new Valyu(); // Use API key with increased_max_results permission

  const response = await valyu.search({
    query: "renewable energy innovations 2025",
    maxNumResults: 100, // Requires increased_max_results permission
  });

  console.log(`Retrieved ${response.results.length} results`);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/search \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "renewable energy innovations 2025",
      "max_num_results": 100
    }'
  ```
</CodeGroup>

### More Guides

<CardGroup cols={2}>
  <Card title="Source Filtering" icon="filter" href="/search/filtering/sources">
    Include or exclude specific domains and datasets
  </Card>

  <Card title="Date Filtering" icon="calendar-days" href="/search/filtering/date">
    Filter by time periods
  </Card>

  <Card title="Prompting Guide" icon="square-pen" href="/search/prompting">
    Write queries that get better results
  </Card>

  <Card title="Tips & Tricks" icon="lightbulb" href="/search/tips-and-tricks">
    Optimise performance and control costs
  </Card>
</CardGroup>

## Response Format

### Example Response

```json theme={null}
{
  "success": true,
  "error": "",
  "tx_id": "tx_12345678-1234-1234-1234-123456789abc",
  "query": "latest developments in quantum computing",
  "results": [
    {
      "title": "Quantum Computing Breakthrough: New Error Correction Method",
      "url": "https://arxiv.org/abs/2024.12345?utm_source=valyu",
      "content": "Researchers at MIT have developed a quantum error correction method that reduces error rates by 90% while maintaining computational speed...",
      "description": "Major breakthrough in quantum error correction methodology",
      "source": "academic",
      "price": 0.005,
      "length": 15420,
      "data_type": "unstructured",
      "source_type": "paper",
      "publication_date": "2024-03-15",
      "id": "https://arxiv.org/abs/2024.12345",
      "image_url": {
        "main": "https://arxiv.org/abs/2024.12345/figure1.jpg"
      },
      "relevance_score": 0.94
    },
    {
      "title": "IBM Announces 1000-Qubit Quantum Processor",
      "url": "https://stackoverflow.com/questions/tagged/quantum-computing?utm_source=valyu",
      "content": "IBM has unveiled its latest quantum processor featuring over 1000 qubits...",
      "description": "IBM's latest quantum hardware milestone announcement",
      "source": "web",
      "price": 0.003,
      "length": 8950,
      "data_type": "unstructured",
      "source_type": "website",
      "publication_date": "2024-05-12",
      "id": "https://stackoverflow.com/questions/tagged/quantum-computing",
      "image_url": {
        "main": "https://stackoverflow.com/static/img/quantum-chip.jpg"
      },
      "relevance_score": 0.87
    }
  ],
  "results_by_source": {
    "academic": 1,
    "web": 1
  },
  "total_results": 25,
  "total_cost_dollars": 0.008,
  "total_characters": 24370
}
```

### Top-level Fields

| **Field**            | **Description**                              |
| -------------------- | -------------------------------------------- |
| `success`            | Whether the search completed successfully    |
| `error`              | Empty on success; error message otherwise    |
| `tx_id`              | Transaction ID for tracing and support       |
| `query`              | The processed search query                   |
| `results`            | Array of result objects, ranked by relevance |
| `results_by_source`  | Count of results per source type             |
| `total_results`      | Total matches available                      |
| `total_cost_dollars` | Total cost in USD                            |
| `total_characters`   | Total characters across all results          |
| `fast_mode`          | Present when fast mode was used              |

### Result Fields

| **Field**          | **Description**                                                    |
| ------------------ | ------------------------------------------------------------------ |
| `title`            | Document or article title                                          |
| `url`              | Canonical URL (may include tracking parameters)                    |
| `content`          | Extracted text, trimmed per `response_length`                      |
| `description`      | Brief summary                                                      |
| `source`           | Source category: `web`, `academic`, etc.                           |
| `price`            | Cost in USD for this result                                        |
| `length`           | Character count                                                    |
| `data_type`        | Data type (e.g., `unstructured`)                                   |
| `source_type`      | Specific source classification (see [Source types](#source-types)) |
| `publication_date` | ISO 8601 date when available                                       |
| `id`               | Stable identifier                                                  |
| `image_url`        | Extracted images                                                   |
| `relevance_score`  | Score between 0 and 1                                              |
| `doi`              | DOI identifier (academic results)                                  |
| `authors`          | Author names (academic results)                                    |
| `citation`         | Citation text (academic results)                                   |
| `citation_count`   | Number of citations (academic results)                             |
| `references`       | References text (academic results)                                 |
| `metadata`         | Additional structured metadata (financial/specialized results)     |

## Source Types

| **Type**         | **Datasets**                             | **Description**                                  |
| ---------------- | ---------------------------------------- | ------------------------------------------------ |
| `general`        | `valyu-wikipedia` and similar corpora    | General knowledge (e.g., Wikipedia)              |
| `website`        | General Web Pages                        | General Web Pages                                |
| `forum`          | Forum Web Pages                          | Forums and Q\&A sites                            |
| `paper`          | `valyu/valyu-arxiv` and academic indexes | Academic papers (ArXiv, etc.)                    |
| `data`           | Finance server integrations              | Market data and analytics                        |
| `report`         | `valyu/valyu-sec-filings`                | SEC regulatory filings                           |
| `health_data`    | WHO Global Health Observatory            | Global health indicators                         |
| `clinical_trial` | `valyu/valyu-clinical-trials`            | Clinical trial summaries from ClinicalTrials.gov |
| `drug_label`     | `valyu/valyu-drug-labels`                | FDA drug labels from DailyMed                    |
| `grants`         | NIH RePORTER                             | NIH funding data                                 |

## Best Practices

1. **Be specific** - Detailed queries get better results
2. **Set price limits** - Balance cost with quality
3. **Use filters** - Get only what you need
4. **Match search type** - Pick `search_type` based on your use case
5. **Track costs** - Check `total_cost_dollars` in responses
6. **Set `is_tool_call=true`** - For AI agent usage

See our [Tips & Tricks](/search/tips-and-tricks) and [Prompting Guide](/search/prompting) for more.

### Error Handling

```python theme={null}
from valyu import Valyu

valyu = Valyu()

try:
    response = valyu.search(
        query="quantum computing applications",
        max_num_results=10,
        search_type="all",
    )

    if response.get("success"):
        for result in response["results"]:
            print(f"Found: {result['title']}")
            print(f"Source: {result['source_type']}")
    else:
        print(f"Search failed: {response.get('error', 'Unknown error')}")

except Exception as e:
    print(f"Request failed: {e}")
```

<Card title="Try the Search API" icon="rocket" href="/api-reference/endpoint/deepsearch">
  Full API reference with interactive examples
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/endpoint/deepsearch">
    Complete parameter documentation
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python-sdk">
    Python integration
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdk/typescript-sdk">
    TypeScript integration
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations/langchain">
    LangChain, LlamaIndex, and more
  </Card>
</CardGroup>