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

> Advanced search across web and proprietary data sources with the Valyu TypeScript SDK

The Search API provides powerful search capabilities across web and proprietary data sources, returning relevant content optimized for AI applications and RAG pipelines.

## Basic Usage

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

const valyu = new Valyu();

const response = await valyu.search(
  "What are the latest developments in quantum computing?"
);

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

## Parameters

### Query (Required)

| Parameter | Type   | Description                                                        |
| --------- | ------ | ------------------------------------------------------------------ |
| `query`   | string | The search query string (see [Prompting Guide](/search/prompting)) |

### Options (Optional)

| Parameter            | Type                                              | Description                                                                                                                                     | Default   |
| -------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `searchType`         | `"web"` \| `"proprietary"` \| `"all"` \| `"news"` | Search type: `"web"` (web only), `"proprietary"` (Valyu datasets), `"news"` (news only), `"all"` (both)                                         | `"all"`   |
| `maxNumResults`      | number                                            | Maximum results to return (1-20 standard, up to 100 with [special API key](http://platform.valyu.ai/user/account/apikeys?req=increase_results)) | 10        |
| `maxPrice`           | number                                            | Maximum cost per thousand retrievals (CPM). Auto-adjusts if not provided                                                                        | undefined |
| `isToolCall`         | boolean                                           | Set to `true` for AI agents/tools, `false` for direct user queries                                                                              | true      |
| `relevanceThreshold` | number                                            | Minimum relevance score (0.0-1.0)                                                                                                               | 0.5       |
| `includedSources`    | string\[]                                         | Sources to search within (URLs, domains, or dataset names)                                                                                      | undefined |
| `excludeSources`     | string\[]                                         | Sources to exclude from results                                                                                                                 | undefined |
| `sourceBiases`       | Record\<string, number>                           | Bias values for specific sources (-5 to +5) to influence ranking without hard filtering                                                         | undefined |
| `instructions`       | string                                            | Natural language instructions to help rank results by relevance to user intent. Ignored in fast mode.                                           | undefined |
| `category`           | string                                            | **Deprecated.** Use `instructions` instead. Falls back to this value if `instructions` is not set                                               | undefined |
| `startDate`          | string                                            | Start date for filtering (YYYY-MM-DD)                                                                                                           | undefined |
| `endDate`            | string                                            | End date for filtering (YYYY-MM-DD)                                                                                                             | undefined |
| `countryCode`        | string                                            | 2-letter ISO country code to bias results                                                                                                       | undefined |
| `responseLength`     | string \| number                                  | Content length: `"short"` (25k), `"medium"` (50k), `"large"` (100k), `"max"` (full), or custom count                                            | `"short"` |
| `fastMode`           | boolean                                           | Enable fast mode for reduced latency but shorter results                                                                                        | false     |
| `urlOnly`            | boolean                                           | Return URLs only (no content). Only applies when `searchType` is `"web"` or `"news"`                                                            | false     |

<Tip>
  Check out our other guides for more information on how to best use the Search API: [Quick Start](/search/quickstart#more-guides).
</Tip>

## Response Format

```typescript theme={null}
interface SearchResponse {
  success: boolean;
  error?: string;
  tx_id: string | null;
  query: string;
  results: SearchResult[];
  results_by_source: {
    web: number;
    proprietary: number;
  };
  total_deduction_dollars: number;
  total_characters: number;
}

interface SearchResult {
  title: string;
  url: string;
  content: string;
  description?: string;
  source: string;
  price: number;
  length: number;
  relevance_score: number;
  data_type?: "structured" | "unstructured";
  // Additional fields for academic/proprietary sources
  publication_date?: string;
  authors?: string[];
  citation?: string;
  citation_count?: number;
  doi?: string;
  references?: string;
  metadata?: Record<string, any>;
}
```

## Parameter Examples

### Fast Mode

Enable fast mode for quicker results:

```typescript theme={null}
const response = await valyu.search(query, {
  fastMode: true,
});
```

Responses will be quicker but the content will be shorter.

### Search Type Configuration

Control which data sources to search:

```typescript theme={null}
// Web search only
const webResponse = await valyu.search(query, {
  searchType: "web",
  maxNumResults: 10
});

// Proprietary datasets only
const proprietaryResponse = await valyu.search(query, {
  searchType: "proprietary",
  maxNumResults: 8
});

// Both web and proprietary (default)
const allResponse = await valyu.search(query, {
  searchType: "all",
  maxNumResults: 12
});
```

### Source Filtering

Control which specific sources to include or exclude:

```typescript theme={null}
const response = await valyu.search(
  "quantum computing applications",
  {
    searchType: "all",
    maxNumResults: 10,
    includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "valyu/valyu-biorxiv"],
    responseLength: "medium"
  }
);
```

```typescript theme={null}
const response = await valyu.search(
  "quantum computing applications",
  {
    searchType: "all",
    maxNumResults: 10,
    excludeSources: ["example.com", "example.org"],
    responseLength: "medium"
  }
);
```

You can either include or exclude sources, but not both.

### Source Biases

Influence ranking without hard filtering. Values range from -5 (strong demotion) to +5 (strong boost):

```typescript theme={null}
const response = await valyu.search(
  "climate change research",
  {
    searchType: "web",
    sourceBiases: {
      "nasa.gov": 5,
      "noaa.gov": 3,
      "epa.gov": 2,
      "nih.gov": 1,
      "example.com": -4
    }
  }
);
```

Source biases can be combined with `includedSources` to control ranking within a filtered pool:

```typescript theme={null}
const response = await valyu.search(
  "climate data",
  {
    includedSources: ["nasa.gov", "noaa.gov", "epa.gov"],
    sourceBiases: {
      "nasa.gov": 5,
      "epa.gov": -3
    }
  }
);
```

URL path specificity is supported — the most specific match wins:

```typescript theme={null}
sourceBiases: {
  "nih.gov": 2,           // General NIH content boosted
  "nih.gov/research": -3  // Specific section demoted
}
```

### Geographic and Date Filtering

Bias results by location and time range:

```typescript theme={null}
const response = await valyu.search(
  "renewable energy policies",
  {
    countryCode: "US",
    startDate: "2024-01-01",
    endDate: "2024-12-31",
    maxNumResults: 7,
    category: "government policy"
  }
);
```

### Response Length Control

Customize content length per result:

```typescript theme={null}
// Predefined lengths
const shortResponse = await valyu.search(query, {
  responseLength: "short" // 25k characters
});

const mediumResponse = await valyu.search(query, {
  responseLength: "medium" // 50k characters
});

const largeResponse = await valyu.search(query, {
  responseLength: "large" // 100k characters
});

// Custom character limit
const customResponse = await valyu.search(query, {
  responseLength: 15000 // Custom limit
});
```

## Use Case Examples

### Academic Research Assistant

Build a comprehensive research tool that searches across academic databases:

```typescript theme={null}
async function academicResearch(query: string) {
  const response = await valyu.search(query, {
    searchType: "proprietary",
    includedSources: ["valyu/valyu-pubmed", "valyu/valyu-arxiv"],
    maxNumResults: 15,
    responseLength: "large",
    category: "academic research"
  });

  if (response.success) {
    console.log(`=== Academic Research Results ===`);
    console.log(`Found ${response.results.length} papers for: "${query}"`);
    
    // Group by source
    const arxivPapers = response.results.filter(r => r.source.includes("arxiv"));
    const pubmedPapers = response.results.filter(r => r.source.includes("pubmed"));
    
    console.log(`\nArXiv Papers: ${arxivPapers.length}`);
    arxivPapers.forEach((paper, i) => {
      console.log(`${i + 1}. ${paper.title}`);
      console.log(`   Relevance: ${paper.relevance_score.toFixed(2)}`);
      console.log(`   URL: ${paper.url}`);
      if (paper.publication_date) {
        console.log(`   Published: ${paper.publication_date}`);
      }
      if (paper.authors) {
        console.log(`   Authors: ${paper.authors.join(", ")}`);
      }
    });
    
    console.log(`\nPubMed Articles: ${pubmedPapers.length}`);
    pubmedPapers.forEach((article, i) => {
      console.log(`${i + 1}. ${article.title}`);
      console.log(`   Relevance: ${article.relevance_score.toFixed(2)}`);
      if (article.citation) {
        console.log(`   Citation: ${article.citation}`);
      }
    });
    
    return {
      arxiv: arxivPapers,
      pubmed: pubmedPapers,
      query
    };
  }
  
  return null;
}

// Usage examples - dates are included in natural language
const covidResearch = await academicResearch(
  "COVID-19 vaccine efficacy studies published between 2023 and 2024"
);

const aiResearch = await academicResearch(
  "recent machine learning breakthroughs in the last 2 years"
);

const climateResearch = await academicResearch(
  "climate change mitigation strategies peer-reviewed research since 2020"
);
```

### Financial Market Intelligence

Create a financial analysis tool that searches market data and news:

```typescript theme={null}
async function financialIntelligence(query: string, analysisType: "fundamental" | "technical" | "news") {
  const sources = {
    fundamental: ["valyu/valyu-stocks", "sec.gov", "sec.gov"],
    technical: ["valyu/valyu-stocks", "kaggle.com", "yahoo.com"],
    news: ["treasury.gov", "federalreserve.gov", "sec.gov", "fred.stlouisfed.org"]
  };

  const response = await valyu.search(query, {
    searchType: analysisType === "fundamental" || analysisType === "technical" ? "all" : "web",
    includedSources: sources[analysisType],
    maxNumResults: 10,
    responseLength: "medium",
    category: "financial analysis"
  });

  if (response.success) {
    console.log(`=== ${analysisType.toUpperCase()} Analysis ===`);
    console.log(`Query: "${query}"`);
    
    response.results.forEach((result, i) => {
      console.log(`\n${i + 1}. ${result.title}`);
      console.log(`   Source: ${result.source}`);
      console.log(`   Relevance: ${result.relevance_score.toFixed(2)}`);
      console.log(`   URL: ${result.url}`);
      
      // Show excerpt for financial data
      if (result.content.length > 200) {
        console.log(`   Preview: ${result.content.substring(0, 200)}...`);
      }
      
      if (result.publication_date) {
        console.log(`   Date: ${result.publication_date}`);
      }
    });
    
    return {
      results: response.results,
      analysisType,
      query
    };
  }
  
  return null;
}

// Usage examples - include timeframes in natural language
const teslaFundamentals = await financialIntelligence(
  "Tesla financial performance Q3 2024 earnings revenue profit margins", 
  "fundamental"
);

const appleNews = await financialIntelligence(
  "Apple latest news this week product announcements stock updates", 
  "news"
);

const bitcoinTechnical = await financialIntelligence(
  "Bitcoin price analysis technical indicators support resistance levels recent trends",
  "technical"
);
```

### Real-time News Monitoring

Build a news monitoring system using news mode with date and country filtering. Supports up to 100 results with the `increased_max_results` permission.

```typescript theme={null}
interface NewsMonitoringOptions {
  daysBack?: number;
  country?: string;
}

async function newsMonitoring(
  queries: string[],
  options: NewsMonitoringOptions = {}
) {
  const { daysBack = 7, country = "US" } = options;
  
  const endDate = new Date().toISOString().split("T")[0];
  const startDate = new Date(Date.now() - daysBack * 24 * 60 * 60 * 1000)
    .toISOString()
    .split("T")[0];

  const allResults = [];
  
  for (const query of queries) {
    const response = await valyu.search(query, {
      searchType: "news", // Use news mode
      maxNumResults: 50, // Up to 100 with increased_max_results permission
      startDate,
      endDate,
      countryCode: country,
      responseLength: "short"
    });

    if (response.success) {
      allResults.push({
        query,
        articles: response.results,
        count: response.results.length
      });
    }
  }

  // Generate monitoring report
  console.log(`=== News Monitoring Report ===`);
  console.log(`Date range: ${startDate} to ${endDate}`);
  console.log(`Country: ${country}`);
  console.log(`Monitoring ${queries.length} topics\n`);
  
  allResults.forEach(({ query, articles, count }) => {
    console.log(`📰 ${query.toUpperCase()}: ${count} articles`);
    
    articles.slice(0, 5).forEach((article, i) => {
      console.log(`   ${i + 1}. ${article.title}`);
      console.log(`      Date: ${article.publication_date || "N/A"}`);
      console.log(`      URL: ${article.url}`);
    });
    console.log("");
  });

  return allResults;
}

// Monitor tech news from the last 7 days in the US
const techNews = await newsMonitoring(
  [
    "artificial intelligence breakthroughs",
    "quantum computing progress", 
    "cryptocurrency regulation"
  ],
  { daysBack: 7, country: "US" }
);

// Monitor business news from the last 30 days
const businessNews = await newsMonitoring(
  [
    "Tesla earnings report",
    "Federal Reserve interest rate decisions",
    "tech layoffs announcements"
  ],
  { daysBack: 30, country: "US" }
);
```

<Tip>
  To use more than 20 results, request the `increased_max_results` permission at [API Key Management](http://platform.valyu.ai/user/account/apikeys?req=increase_results).
</Tip>

## Error Handling

The Search API includes comprehensive error handling and validation:

```typescript theme={null}
const response = await valyu.search("test query", {
  maxNumResults: 5
});

if (!response.success) {
  console.error("Search failed:", response.error);
  
  // Handle specific error cases
  if (response.error?.includes("insufficient credits")) {
    console.log("Please add more credits to your account");
  } else if (response.error?.includes("invalid")) {
    console.log("Check your search parameters");
  }
  
  return;
}

// Process successful results
console.log(`Transaction ID: ${response.tx_id}`);

response.results.forEach((result, index) => {
  console.log(`${index + 1}. ${result.title}`);
  console.log(`   Relevance: ${result.relevance_score}`);
  console.log(`   Source: ${result.source}`);
  console.log(`   URL: ${result.url}`);
});
```

## Source Types

### Web Sources

* General websites and domains
* News sites and blogs
* Forums and community sites
* Documentation sites

### Proprietary Sources

* `valyu/valyu-arxiv` - Academic papers from arXiv
* `valyu/valyu-pubmed` - Medical and life science literature
* `valyu/valyu-stocks` - Global stock market data
* And many more. Check out the [Valyu Platform Datasets](https://platform.valyu.ai/data-sources) for more information.