Search API

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

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)

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

Check out our other guides for more information on how to best use the Search API: Quick Start.

Response Format

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:

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:

// 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:

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

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

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:

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:

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:

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:

// 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:

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:

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.

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" }
);

To use more than 20 results, request the increased_max_results permission at API Key Management.

Error Handling

The Search API includes comprehensive error handling and validation:

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}`);
});

Basic Usage

Parameters

Query (Required)

Options (Optional)

Response Format

Parameter Examples

Fast Mode

Search Type Configuration

Source Filtering

Source Biases

Geographic and Date Filtering

Response Length Control

Use Case Examples

Academic Research Assistant

Financial Market Intelligence

Real-time News Monitoring

Error Handling

Source Types

Web Sources

Proprietary Sources

Documentation Index

​Basic Usage

​Parameters

​Query (Required)

​Options (Optional)

​Response Format

​Parameter Examples

​Fast Mode

​Search Type Configuration

​Source Filtering

​Source Biases

​Geographic and Date Filtering

​Response Length Control

​Use Case Examples

​Academic Research Assistant

​Financial Market Intelligence

​Real-time News Monitoring

​Error Handling

​Source Types

​Web Sources

​Proprietary Sources

Basic Usage

Parameters

Query (Required)

Options (Optional)

Response Format

Parameter Examples

Fast Mode

Search Type Configuration

Source Filtering

Source Biases

Geographic and Date Filtering

Response Length Control

Use Case Examples

Academic Research Assistant

Financial Market Intelligence

Real-time News Monitoring

Error Handling

Source Types

Web Sources

Proprietary Sources