DeepResearch API | TypeScript SDK

DeepResearch plans, searches, verifies, and writes a cited report. Tasks run async - create one, then poll or wait for the result.

For the conceptual overview, search configuration, and best practices, see the DeepResearch Guide. This page is the TypeScript SDK method reference.

Wire up Valyu DeepResearch (autonomous research agent) with the TypeScript SDK.

Open in Cursor

Basic usage

import { Valyu } from "valyu-js";

const valyu = new Valyu();

const task = await valyu.deepresearch.create({
  query: "What are the key differences between RAG and fine-tuning for LLMs?",
  mode: "standard",
});

if (task.success) {
  const result = await valyu.deepresearch.wait(task.deepresearch_id, {
    onProgress: (s) => console.log(`Status: ${s.status}`),
  });
  if (result.status === "completed") {
    console.log(result.output);
    console.log(`Cost: $${result.cost}`);
  }
}

Research modes

Mode	Best for	Typical time	Price
`fast`	Quick lookups, lightweight research	~5 min	$0.10
`standard`	Balanced research (default)	~10-20 min	$0.50
`heavy`	In-depth, complex analysis	up to ~90 min	$2.50
`max`	Exhaustive research with fact verification	up to ~180 min	$15.00

The deprecated lite mode maps to standard. max requires at least $15 in available credits.

Output formats

// Markdown (default), optionally with a downloadable PDF
await valyu.deepresearch.create({ query: "...", outputFormats: ["markdown", "pdf"] });

// Structured JSON - pass a single JSON Schema instead of markdown/pdf
await valyu.deepresearch.create({
  query: "Research competitor pricing in the SaaS market",
  outputFormats: [{
    type: "object",
    properties: {
      competitors: { type: "array", items: { type: "object", properties: {
        name: { type: "string" }, pricing_model: { type: "string" },
      } } },
      market_summary: { type: "string" },
    },
    required: ["competitors", "market_summary"],
  }],
});

You cannot mix a JSON Schema with markdown/pdf. TOON format also requires a JSON schema.

Waiting for completion

const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  pollInterval: 5000,    // ms between status checks
  maxWaitTime: 900000,   // timeout in ms (raise for heavy/max)
  onProgress: (s) => console.log(s.status),
});

In production, prefer webhooks over polling. The webhook_secret is returned only once on create - store it immediately:

const task = await valyu.deepresearch.create({
  query: "Research market trends in AI",
  webhookUrl: "https://your-app.com/webhooks/deepresearch",
});
const webhookSecret = task.webhook_secret; // store securely - not retrievable later

Mode	Poll interval	Timeout
`fast`	2-5s	10 min
`standard`	5-10s	30 min
`heavy`	10-30s	120 min
`max`	30-60s	180 min

Reference

create() options

query (string, required) - research query or task description.

Option	Type	Description	Default
`mode`	`"fast"` \| `"standard"` \| `"heavy"` \| `"max"`	Research mode	`"standard"`
`outputFormats`	array	`["markdown"]`, `["markdown", "pdf"]`, or a single JSON schema	`["markdown"]`
`researchStrategy`	string	Natural-language strategy to guide research	undefined
`reportFormat`	string	Natural-language output format instructions (highest priority)	undefined
`search`	object	Search config (filters, date range). See the DeepResearch Guide	undefined
`urls`	string[]	URLs to analyze (max 10)	undefined
`files`	FileAttachment[]	File attachments (max 10)	undefined
`deliverables`	`(string \| Deliverable)[]`	Additional file outputs (max 10)	undefined
`mcpServers`	MCPServerConfig[]	MCP server configs (max 5)	undefined
`tools`	DeepResearchTools	Optional agent tools, each off by default	undefined
`previousReports`	string[]	Previous task IDs for context (max 3)	undefined
`webhookUrl`	string	HTTPS URL for completion notification	undefined
`metadata`	object	Custom metadata for tracking	undefined
`alertEmail`	string \| AlertEmailConfig	Email for completion notifications	undefined
`hitl`	HitlConfig	Human-in-the-loop checkpoints. See HITL. Not available for batch	undefined

Tools (code execution, screenshots, browser, charts)

All tools are off by default. You enable them; the agent decides when to use them. Each accepts a boolean or { enabled: boolean, max_calls: number } (max_calls can only be lowered from the system default).

Tool	Description	Default max_calls
`code_execution`	Run sandboxed Python (no network). Required for XLSX/PPTX/DOCX deliverables	10
`screenshots`	Capture page screenshots (charts, dashboards)	15
`browser_use`	Autonomous browser sessions	5
`charts`	Generate charts embedded in the report. Free, unlimited	-

const task = await valyu.deepresearch.create({
  query: "Analyse Tesla's Q3 earnings. Screenshot revenue charts and calculate YoY growth.",
  mode: "heavy",
  tools: {
    code_execution: { enabled: true },
    screenshots: { enabled: true, max_calls: 5 },
    charts: true,
  },
});

Generated screenshots and charts appear in result.images with image_type of "screenshot" or "chart". See Pricing for surcharges. Code execution is Python-only with a 30s default timeout (5-60s); screenshots are capped at 15 per task and 5 MB each.

Deliverables (CSV, Excel, PowerPoint, Word, PDF)

Generate formatted documents from the research (max 10 per task, produced after research completes). Use simple strings or the typed Deliverable:

const task = await valyu.deepresearch.create({
  query: "Research the top 20 AI companies in 2024",
  deliverables: [
    "CSV file with company names, founding year, and funding",
    { type: "pptx", description: "Executive summary", slides: 10, template: "modern" },
  ],
});

for (const d of (await valyu.deepresearch.wait(task.deepresearch_id)).deliverables ?? []) {
  if (d.status === "completed") console.log(d.title, d.url);
}

Type	Optional fields
`csv`	`columns`, `includeHeaders`
`xlsx`	`columns`, `includeHeaders`, `sheetName`
`pptx`	`slides`, `template`
`docx`	`template`
`pdf`	`template`

Each DeliverableResult has id, type, status, title, url (token-signed, expires), row_count/column_count (CSV/Excel), and error if failed.

File attachments and URLs

import * as fs from "fs";

const pdfData = fs.readFileSync("report.pdf").toString("base64");

const task = await valyu.deepresearch.create({
  query: "Summarize the key findings and compare with market trends",
  mode: "heavy",
  files: [{
    data: `data:application/pdf;base64,${pdfData}`,
    filename: "report.pdf",
    mediaType: "application/pdf",
    context: "Q4 2024 financial report",
  }],
  urls: ["https://example.com/article-1"],
});

Supported file types: PDFs, images (PNG, JPEG, WebP), and documents.

Response format

interface DeepResearchStatusResponse {
  success: boolean;
  deepresearch_id?: string;
  status?: "queued" | "running" | "completed" | "failed" | "cancelled" | "awaiting_input" | "paused";
  query?: string;
  mode?: "fast" | "standard" | "heavy" | "max";
  output_type?: "markdown" | "json" | "toon";
  output?: string | Record<string, any>;
  sources?: DeepResearchSource[];
  cost?: number;
  cost_breakdown?: DeepResearchCostBreakdown;
  tools?: DeepResearchTools;
  created_at?: string;
  completed_at?: string;
  pdf_url?: string;
  images?: ImageMetadata[];
  deliverables?: DeliverableResult[];
  batch_id?: string;
  batch_task_id?: string;
  error?: string;
}

interface DeepResearchSource {
  title: string;
  url: string;
  snippet?: string;
  source?: string;  // web, pubmed, arxiv, etc.
  word_count?: number;
  doi?: string;
  fragment?: string;  // append to url for a deep-link to the cited passage
}

cost is the total price (base mode + tool surcharges); cost_breakdown itemizes it.

Task management

await valyu.deepresearch.status(taskId);                  // current status + progress
await valyu.deepresearch.update(taskId, "Focus on 2024 peer-reviewed sources"); // follow-up (before writing phase)
await valyu.deepresearch.respond(taskId, interactionId, { approved: true });    // answer a HITL checkpoint
await valyu.deepresearch.cancel(taskId);
await valyu.deepresearch.delete(taskId);
await valyu.deepresearch.list({ limit: 50 });
await valyu.deepresearch.togglePublic("dr_abc123", true);

// Download authenticated assets (images, charts, deliverables, PDFs)
const asset = await valyu.deepresearch.getAssets(taskId, assetId);
if (asset.success && asset.data) fs.writeFileSync("output.png", asset.data);

Follow-up instructions via update() are only accepted before the writing phase starts.

DeepResearch Guide

Search config, webhooks, and use cases

Batch Processing

Run many research tasks in parallel

Human-in-the-loop

Pause at checkpoints to guide the agent

API Reference

REST endpoint documentation

SDKs

DeepResearch

Basic usage

Research modes

Output formats

Waiting for completion

Reference

See also

DeepResearch Guide

Batch Processing

Human-in-the-loop

API Reference

​Basic usage

​Research modes

​Output formats

​Waiting for completion

​Reference

​See also

DeepResearch Guide

Batch Processing

Human-in-the-loop

API Reference

Basic usage

Research modes

Output formats

Waiting for completion

Reference

See also