Skip to main content
Search across web and proprietary data sources, returning content optimized for AI applications and RAG pipelines.

Wire up Valyu Search with the TypeScript SDK.

Open in Cursor

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(result.title, "-", result.url);
  console.log(result.content.substring(0, 200), "...");
});

Common patterns

// Fast mode - lower latency, shorter content
await valyu.search(query, { fastMode: true });

// Restrict to specific sources (datasets, domains, or presets)
await valyu.search("quantum computing applications", {
  includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed"],
  responseLength: "medium",
});
// ...or exclude sources instead (use one or the other, not both)
await valyu.search(query, { excludeSources: ["example.com"] });

// Bias ranking without hard filtering (-5 demote ... +5 boost)
await valyu.search("climate change research", {
  sourceBiases: { "nasa.gov": 5, "noaa.gov": 3, "example.com": -4 },
});

// Filter by country and date range
await valyu.search("renewable energy policies", {
  countryCode: "US",
  startDate: "2024-01-01",
  endDate: "2024-12-31",
});

// News mode (up to 100 results with the increased_max_results permission)
await valyu.search("AI breakthroughs", { searchType: "news", maxNumResults: 50 });
Source biases support URL-path specificity - the most specific match wins ({ "nih.gov": 2, "nih.gov/research": -3 }).
Building a multi-step research flow on top of Search? Consider DeepResearch - a cost-effective autonomous agent purpose-built for reports, diligence, and market sizings.

Reference

query (string, required) - the search query. See the Prompting Guide.
ParameterTypeDescriptionDefault
searchType"web" | "proprietary" | "all" | "news"Which sources to search"all"
maxNumResultsnumberResults to return (1-20, up to 100 with the increased_max_results permission)10
maxPricenumberMax cost per thousand retrievals (CPM). Auto-adjusts if not providedundefined
isToolCallbooleantrue for AI agents/tools, false for direct user queriestrue
relevanceThresholdnumberMinimum relevance score (0.0-1.0)0.5
includedSourcesstring[]Sources to search within (dataset ids, domains, or presets)undefined
excludeSourcesstring[]Sources to excludeundefined
sourceBiasesRecord<string, number>Bias ranking per source (-5 to +5) without hard filteringundefined
instructionsstringNatural-language instructions to rank by intent. Ignored in fast modeundefined
categorystringDeprecated. Use instructionsundefined
startDate / endDatestringDate filter (YYYY-MM-DD)undefined
countryCodestring2-letter ISO country code to bias resultsundefined
responseLengthstring | number"short" (25k), "medium" (50k), "large" (100k), "max" (full), or a custom character count"short"
fastModebooleanReduced latency, shorter resultsfalse
urlOnlybooleanReturn URLs only (no content). Applies when searchType is "web" or "news"false
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";
  // Academic/proprietary sources also populate:
  publication_date?: string;
  authors?: string[];
  citation?: string;
  citation_count?: number;
  doi?: string;
  references?: string;
  metadata?: Record<string, any>;
}

Source types

  • Web - general websites, news, blogs, forums, documentation.
  • Proprietary - valyu/valyu-arxiv (arXiv papers), valyu/valyu-pubmed (medical literature), valyu/valyu-stocks (market data), and many more.
Browse the full catalog on the Valyu Platform.