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

| 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

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

Workflows

Templated DeepResearch starting points - curated by Valyu or created by your org - with typed {variable} placeholders and version history.

// Browse curated workflows
const catalog = await valyu.workflows.list({ scope: "valyu", vertical: "investment-banking" });
for (const wf of catalog.workflows ?? []) {
  console.log(`${wf.slug} - ${wf.title}`);
}

// Run one as a DeepResearch task
const task = await valyu.deepresearch.create({
  workflowId: "ib-company-profile",
  workflowParams: { company: "NVIDIA (NVDA)" },
});

const result = await valyu.deepresearch.wait(task.deepresearch_id);
console.log(result.output);

Create your own:

await valyu.workflows.create({
  slug: "weekly-competitor-scan",
  title: "Weekly Competitor Scan",
  version: {
    prompt: "Summarize the week's most important developments at {company}.",
    strategy: "Prioritize primary sources: filings, press releases, earnings calls.",
    report_format: "Bullet-point briefing, grouped by theme.",
    variables: [{ key: "company", label: "Company", required: true }],
  },
});

| Method | Description | |---|---| | list(options?) | List available workflows (filter by vertical, scope, tags, free text) | | get(slug, version?) | Get a workflow's full template | | versions(slug) | List a workflow's version history | | preview(slug, options?) | Resolve the template without creating a task | | create(options) | Create an org workflow | | update(slug, options) | Update metadata and/or publish a new version | | delete(slug) | Delete an org workflow |

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