DeepResearch API in TypeScript | Valyu TypeScript SDK

Run a multi-step investigation and retrieve a cited report or structured output. Create a task, retain its ID, then wait for completion or receive a webhook.

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

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 && task.deepresearch_id) {
  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

Set mode to fast (25 credits per task), standard (100 credits), heavy (500) or max (2,500). Tool and deliverable charges can apply; see pricing and the DeepResearch guide for mode selection.

When mode is omitted, the TypeScript SDK sends fast. The API and the Python SDK default to standard. Pass mode explicitly.

Creating a task holds its mode price against your balance, so you need at least that amount available (for example 2,500 credits for max). See billing and credit holds for the 402 and 503 responses.

instant mode is not in the SDK’s mode type yet. Call the create endpoint directly to use it.

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	15 min
`standard`	5-10s	30 min
`heavy`	10-30s	60 min
`max`	30-60s	120 min

Reference

create() options

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

Option	Type	Description	Default
`mode`	`"fast"` \| `"standard"` \| `"heavy"` \| `"max"`	Research mode	`"fast"` (the API default is `"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. No additional chart charge	-

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",
  tools: { code_execution: true },
  deliverables: [
    "CSV file with company names, founding year, and funding",
    { type: "pptx", description: "Executive summary", slides: 10, template: "modern" },
  ],
});

if (!task.success || !task.deepresearch_id) throw new Error(task.error);

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

Start here

APIs

Finance workflows

Sciences workflows

Build and connect

Comparisons

TypeScript SDK: 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