Valyu JavaScript SDK

Search and research APIs built for AI agents. Access web and proprietary data sources through Search, extract content from URLs, generate grounded answers, and run multi-step research with DeepResearch - all through a single SDK.

Documentation | API Reference | Platform

Installation

npm install valyu-js

Quick Start

import { Valyu } from "valyu-js";

const valyu = new Valyu(process.env.VALYU_API_KEY);

const response = await valyu.search("latest advances in transformer architectures", {
  maxNumResults: 5,
  searchType: "all",
});

for (const result of response.results) {
  console.log(result.title, result.url);
}

Get $10 free credits when you sign up at platform.valyu.ai. No credit card required.

APIs

Search

Search across web and proprietary data sources with a single query.

const response = await valyu.search("CRISPR gene therapy clinical trials 2026", {
  searchType: "proprietary",                    // "all", "web", or "proprietary"
  maxNumResults: 10,                            // 1-20 results
  includedSources: ["valyu/valyu-pubmed"],      // filter to specific sources
  startDate: "2026-01-01",                      // date filtering
  endDate: "2026-12-31",
});

All search parameters

Parameter	Type	Default	Description
query	string	required	Search query
searchType	string	"all"	"all", "web", or "proprietary"
maxNumResults	number	10	Results to return (1-20)
maxPrice	number	30	Max price per thousand queries (CPM)
relevanceThreshold	number	0.5	Min relevance score (0-1)
includedSources	string[]	[]	Sources to search
excludeSources	string[]	[]	Sources to exclude
startDate	string	-	Start date (YYYY-MM-DD)
endDate	string	-	End date (YYYY-MM-DD)
countryCode	string	-	Country filter (e.g. "US", "GB")
responseLength	string | number	-	"short", "medium", "large", "max", or character count
category	string	-	Category filter

Contents

Extract clean, structured content from URLs. Supports sync (1-10 URLs) and async (up to 50 URLs) modes.

// Basic extraction
const response = await valyu.contents(["https://arxiv.org/abs/2301.00001"]);

// With AI summarization
const response = await valyu.contents(["https://example.com/article"], {
  summary: true,
  responseLength: "medium",
});

// Structured data extraction with JSON schema
const response = await valyu.contents(["https://en.wikipedia.org/wiki/OpenAI"], {
  summary: {
    type: "object",
    properties: {
      company_name: { type: "string" },
      founded_year: { type: "integer" },
    },
  },
});

Answer

AI-generated answers grounded by Valyu's search. Supports streaming.

const response = await valyu.answer("What are the side effects of metformin?", {
  searchType: "proprietary",
  includedSources: ["valyu/valyu-pubmed"],
});

console.log(response.contents);        // AI-generated answer
console.log(response.search_results);  // Source citations

DeepResearch

Multi-step research agent that produces comprehensive reports with citations.

// Start a research task
const task = await valyu.deepresearch.create({
  query: "Compare CRISPR and base editing approaches for sickle cell disease",
  model: "heavy",
  outputFormats: ["markdown", "pdf"],
});

// Wait for completion with progress
const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  onProgress: (status) => {
    console.log(`Step ${status.progress.current_step}/${status.progress.total_steps}`);
  },
});

console.log(result.output);   // Markdown report
console.log(result.pdf_url);  // PDF download link

All DeepResearch methods

Method	Description
create(options)	Start a new research task
status(taskId)	Get task status
wait(taskId, options?)	Poll until completion
stream(taskId, callbacks)	Stream real-time updates
list(options)	List research tasks
update(taskId, instruction)	Add follow-up instruction
cancel(taskId)	Cancel a running task
delete(taskId)	Delete a task
togglePublic(taskId, isPublic)	Toggle public access

Batch

Run multiple DeepResearch tasks in parallel.

const batch = await valyu.batch.create({
  name: "Q1 Analysis",
  mode: "fast",
  outputFormats: ["markdown"],
});

await valyu.batch.addTasks(batch.batch_id, {
  tasks: [
    { query: "Analyze recent SPAC performance" },
    { query: "Review semiconductor supply chain trends" },
  ],
});

const result = await valyu.batch.waitForCompletion(batch.batch_id, {
  onProgress: (b) => console.log(`${b.counts.completed}/${b.counts.total}`),
});

Data Sources

List available data sources programmatically.

const sources = await valyu.datasources.list();
const categories = await valyu.datasources.categories();

Authentication

export VALYU_API_KEY="your-api-key"

Or pass directly:

const valyu = new Valyu("your-api-key");

TypeScript

Full type definitions are included. All request and response types are exported:

import { Valyu, SearchOptions, SearchResponse, SearchResult } from "valyu-js";

Error Handling

const response = await valyu.search("test");

if (!response.success) {
  console.error(response.error);
  console.error(`tx_id: ${response.tx_id}`);
}

Integrations

Valyu works with Vercel AI SDK, LangChain, MCP, and more. See docs.valyu.ai for integration guides.

Links

• Documentation
• Platform & API Keys
• Discord
• GitHub Issues

License

MIT