> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepResearch API

> Asynchronous deep research using the Valyu TypeScript SDK

The DeepResearch API performs comprehensive research by searching multiple sources, analyzing content, and generating detailed reports. Tasks run in the background, enabling thorough multi-step research.

<Note>
  For conceptual overview, search configuration details, and best practices, see the [DeepResearch Guide](/guides/deepresearch). This page focuses on TypeScript SDK method reference.
</Note>

## Basic Usage

```typescript theme={null}
import { Valyu } from "valyu-js";

const valyu = new Valyu();

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

if (task.success) {
  console.log(`Task created: ${task.deepresearch_id}`);
  
  // Wait for completion with progress updates
  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

DeepResearch offers four modes optimized for different use cases:

| Mode       | Best For                                                       | Typical Completion Time |
| ---------- | -------------------------------------------------------------- | ----------------------- |
| `fast`     | Quick answers, lightweight research, simple lookups            | \~5 minutes             |
| `standard` | Balanced research, deeper insights without long wait times     | \~10-20 minutes         |
| `heavy`    | In-depth, long-running research tasks, complex analysis        | Up to \~90 minutes      |
| `max`      | Exhaustive research with maximum quality and fact verification | Up to \~180 minutes     |

<Note>
  The `lite` mode is deprecated and maps to `standard`.
</Note>

```typescript theme={null}
// Use fast mode for quick lookups
const task = await valyu.deepresearch.create({
  query: "What is quantum computing?",
  mode: "fast"
});

// Use heavy mode for complex research
const task = await valyu.deepresearch.create({
  query: "Analyze the competitive landscape of cloud computing in 2024",
  mode: "heavy"
});

// Use max mode for exhaustive research
const task = await valyu.deepresearch.create({
  query: "Comprehensive analysis of AI safety research with fact verification",
  mode: "max"
});
```

## Parameters

### Query (Required)

| Parameter | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| `query`   | string | Research query or task description |

### Options (Optional)

| Parameter          | Type                                             | Description                                                                                                                                                  | Default        |
| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `mode`             | `"fast"` \| `"standard"` \| `"heavy"` \| `"max"` | Research mode. The `lite` mode is deprecated and maps to `standard`.                                                                                         | `"standard"`   |
| `outputFormats`    | array                                            | Output formats (see below)                                                                                                                                   | `["markdown"]` |
| `strategy`         | string                                           | **Deprecated.** Use `researchStrategy` instead                                                                                                               | undefined      |
| `researchStrategy` | string                                           | Natural language strategy to guide the research phase                                                                                                        | undefined      |
| `reportFormat`     | string                                           | Natural language instructions for output format (highest priority)                                                                                           | undefined      |
| `search`           | object                                           | Search configuration (filters, date range)                                                                                                                   | undefined      |
| `urls`             | string\[]                                        | URLs to analyze (max 10)                                                                                                                                     | undefined      |
| `files`            | FileAttachment\[]                                | File attachments (max 10)                                                                                                                                    | undefined      |
| `deliverables`     | `(string \| Deliverable)[]`                      | Additional file outputs to generate (max 10)                                                                                                                 | undefined      |
| `mcpServers`       | MCPServerConfig\[]                               | MCP server configurations (max 5)                                                                                                                            | undefined      |
| `tools`            | `DeepResearchTools`                              | Optional agent tools to enable. See [Tools](#tools) below.                                                                                                   | `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` or `AlertEmailConfig`                   | Email for completion notifications. Can be a string or `{email: "...", customUrl: "https://.../{id}"}` with `{id}` placeholder.                              | `undefined`    |
| `hitl`             | `HitlConfig`                                     | Human-in-the-loop configuration. Enable checkpoints that pause at key decision points. See [HITL Guide](/guides/deepresearch-hitl). Not available for batch. | `undefined`    |

## Output Formats

### Markdown (Default)

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Explain quantum computing advancements in 2024",
  outputFormats: ["markdown"]
});
```

### Markdown + PDF

Request both markdown and a downloadable PDF report:

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Write a report on renewable energy trends",
  outputFormats: ["markdown", "pdf"]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id!);

if (result.pdf_url) {
  console.log(`PDF available at: ${result.pdf_url}`);
}
```

### Structured JSON

Get research results in a custom schema using [JSON Schema](https://json-schema.org/understanding-json-schema) specification:

```typescript theme={null}
const task = 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" },
            price_range: { type: "string" },
            key_features: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["name", "pricing_model"]
        }
      },
      market_summary: { type: "string" },
      recommendations: {
        type: "array",
        items: { type: "string" }
      }
    },
    required: ["competitors", "market_summary"]
  }]
});

const result = await valyu.deepresearch.wait(task.deepresearch_id!);

if (result.output_type === "json") {
  const data = result.output as any;
  data.competitors.forEach((competitor: any) => {
    console.log(`${competitor.name}: ${competitor.pricing_model}`);
  });
}
```

### TOON Format

Get research results in [TOON format](https://github.com/toon-format/toon) for structured, machine-readable deliverables. TOON format requires a JSON schema and cannot be mixed with markdown/pdf.

```typescript theme={null}
const task = 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" }
          }
        }
      }
    },
    required: ["competitors"]
  }]
});
```

<Warning>
  You cannot mix JSON Schema with markdown/pdf formats. Use one or the other. TOON format requires a JSON schema.
</Warning>

<Note>
  The schema must be a valid [JSON Schema](https://json-schema.org/understanding-json-schema). Use `type`, `properties`, `required`, `items`, and other standard JSON Schema keywords.
</Note>

## Search Configuration

The `search` parameter controls which data sources are queried. See the [DeepResearch Guide](/guides/deepresearch#search-configuration) for complete documentation of all search options.

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Research AI trends",
  search: {
    searchType: "proprietary",
    includedSources: ["academic", "finance"],
    startDate: "2024-01-01",
    endDate: "2024-12-31",
    countryCode: "US"  // Filter web results by country
  }
});
```

### Search Parameters

| Parameter         | Type                                  | Description                                                                       |
| ----------------- | ------------------------------------- | --------------------------------------------------------------------------------- |
| `searchType`      | `"all"` \| `"web"` \| `"proprietary"` | Which search systems to query                                                     |
| `includedSources` | string\[]                             | Only search these source types                                                    |
| `excludedSources` | string\[]                             | Exclude these source types                                                        |
| `startDate`       | string                                | ISO date (`YYYY-MM-DD`) for minimum date                                          |
| `endDate`         | string                                | ISO date (`YYYY-MM-DD`) for maximum date                                          |
| `category`        | string                                | Filter by category (source-dependent)                                             |
| `countryCode`     | string                                | ISO 3166-1 alpha-2 code (e.g., `"US"`, `"GB"`) for location-filtered web searches |

<Note>
  Available source types: `web`, `academic`, `finance`, `patent`, `transportation`, `politics`, `legal`
</Note>

## Tools

The `tools` parameter controls which optional capabilities the research agent can use during a task. All tools are **off by default** and must be explicitly enabled.

| Tool             | Description                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `code_execution` | Run Python code in a sandboxed environment. Required for XLSX/PPTX/DOCX deliverable generation.                           |
| `screenshots`    | Capture visual screenshots of web pages. The agent decides when screenshots add value (charts, dashboards, infographics). |
| `charts`         | Generate charts and graphs embedded in the final report. Free, no per-call surcharge.                                     |

See [Pricing](/pricing#tool-surcharges) for per-tool surcharge details.

<Note>
  You enable tools — the **agent decides when to use them**. For example, enabling `screenshots` does not screenshot every page; the agent selects pages where visual context is valuable.
</Note>

### Enabling tools

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Analyse Tesla's Q3 2026 earnings. Screenshot their investor relations page and any revenue charts. Calculate YoY revenue growth rates and operating margins.",
  mode: "heavy",
  tools: {
    code_execution: true,
    screenshots: true,
    charts: true,
  },
});
```

### Screenshots

When `screenshots` is enabled, captured screenshots appear in the `images` array with `image_type: "screenshot"`:

```typescript theme={null}
const result = await valyu.deepresearch.wait(task.deepresearch_id!);

for (const image of result.images ?? []) {
  if (image.image_type === "screenshot") {
    console.log(`Screenshot of ${image.source_url}: ${image.image_url}`);
  }
}
```

Screenshot-specific fields on `ImageMetadata`:

| Field         | Type   | Description                                       |
| ------------- | ------ | ------------------------------------------------- |
| `source_url`  | string | The original web page URL that was screenshotted  |
| `captured_at` | number | Unix timestamp (ms) when the screenshot was taken |

**Limits:**

* Max 15 screenshots per task
* Max 5 MB per screenshot
* Images capped at 1280 × 4000 px in reports

### Code execution

When `code_execution` is enabled, the agent can run Python code in a sandboxed environment with no network access.

**Limits:**

* Python only
* 30-second default timeout per execution (5–60s range)
* No internet access
* Text output only via `print()`

### Charts

When `charts` is enabled, the agent can generate charts and graphs to visualize data gathered during research. Charts are rendered server-side and embedded directly in the final report.

```typescript theme={null}
const result = await valyu.deepresearch.wait(task.deepresearch_id!);

for (const image of result.images ?? []) {
  if (image.image_type === "chart") {
    console.log(`${image.chart_type}: ${image.image_url}`);
  }
}
```

Chart-specific fields on `ImageMetadata`:

| Field          | Type   | Description                                                                                                                                                                             |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chart_type`   | string | One of `line`, `bar`, `area`, `pie`, `doughnut`, `radar`, `scatter`, `horizontalBar`, `heatmap`, `boxplot`, `stackedBar`, `stackedArea`, `histogram`, `waterfall`, `timeline`, `bubble` |
| `x_axis_label` | string | Label for the x-axis                                                                                                                                                                    |
| `y_axis_label` | string | Label for the y-axis                                                                                                                                                                    |
| `data_series`  | array  | Series data the chart was rendered from                                                                                                                                                 |

**Notes:**

* Free, no per-call surcharge
* Unlimited charts per task
* The agent decides when a chart adds value to the report

## File Attachments

Analyze documents as part of research:

```typescript theme={null}
import * as fs from "fs";

// Read and encode a PDF
const pdfBuffer = fs.readFileSync("report.pdf");
const pdfData = pdfBuffer.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"  // Optional context
  }]
});
```

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

## Deliverables

Generate additional file outputs alongside the research report. Deliverables allow you to extract structured data or create formatted documents (CSV, Excel, PowerPoint, Word, PDF) from the research.

### Simple Deliverables

Use simple strings to describe what you need:

```typescript theme={null}
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",
    "PowerPoint presentation with 5 slides summarizing key findings"
  ]
});

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

if (result.deliverables) {
  for (const deliverable of result.deliverables) {
    if (deliverable.status === "completed") {
      console.log(`✅ ${deliverable.title}`);
      console.log(`   Download: ${deliverable.url}`);
      if (deliverable.row_count) {
        console.log(`   Rows: ${deliverable.row_count}`);
      }
    }
  }
}
```

### Structured Deliverables

Use the `Deliverable` type for precise control:

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Analyze startup funding trends in 2024",
  deliverables: [
    {
      type: "xlsx",
      description: "Startup funding data with company details",
      columns: ["Company", "Funding Amount", "Date", "Investors", "Stage"],
      includeHeaders: true,
      sheetName: "Funding Data"
    },
    {
      type: "pptx",
      description: "Executive summary presentation",
      slides: 10,
      template: "modern"
    },
    {
      type: "pdf",
      description: "Detailed analysis report with charts and insights"
    }
  ]
});

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

// Access deliverables
for (const deliverable of result.deliverables) {
  console.log(`${deliverable.type.toUpperCase()}: ${deliverable.title}`);
  console.log(`Status: ${deliverable.status}`);
  if (deliverable.status === "completed") {
    console.log(`Download: ${deliverable.url}`);
  } else if (deliverable.status === "failed") {
    console.log(`Error: ${deliverable.error}`);
  }
}
```

### Deliverable Types

| Type   | Description             | Optional Fields                          |
| ------ | ----------------------- | ---------------------------------------- |
| `csv`  | Comma-separated values  | `columns`, `includeHeaders`              |
| `xlsx` | Excel spreadsheet       | `columns`, `includeHeaders`, `sheetName` |
| `pptx` | PowerPoint presentation | `slides`, `template`                     |
| `docx` | Word document           | `template`                               |
| `pdf`  | PDF document            | `template`                               |

### Deliverable Response

```typescript theme={null}
interface DeliverableResult {
  id: string;
  request: string;  // Original description
  type: "csv" | "xlsx" | "pptx" | "docx" | "pdf" | "unknown";
  status: "completed" | "failed";
  title: string;  // Generated filename
  url: string;  // Download URL (token-signed, expires)
  s3_key: string;
  row_count?: number;  // For CSV/Excel
  column_count?: number;  // For CSV/Excel
  error?: string;  // If failed
  created_at: string;  // ISO 8601 timestamp string
}
```

<Note>
  You can request up to 10 deliverables per research task. Deliverables are generated after the research completes.
</Note>

## URL Extraction

Include specific URLs to analyze alongside web research:

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Compare the approaches described in these articles",
  urls: [
    "https://example.com/article-1",
    "https://example.com/article-2"
  ]
});
```

## Waiting for Completion

### Basic Wait

```typescript theme={null}
const result = await valyu.deepresearch.wait(task.deepresearch_id!);

if (result.status === "completed") {
  console.log(result.output);
}
```

### With Progress Callback

Track research progress in real-time:

```typescript theme={null}
const result = await valyu.deepresearch.wait(task.deepresearch_id!, {
  pollInterval: 5000,      // Check every 5 seconds
  maxWaitTime: 900000,     // Timeout after 15 minutes (standard mode)
  onProgress: (status) => {
    if (status.progress) {
      const pct = (status.progress.current_step / status.progress.total_steps) * 100;
      console.log(`Progress: ${pct.toFixed(0)}% - Step ${status.progress.current_step}/${status.progress.total_steps}`);
    }
    console.log(`Status: ${status.status}`);
  }
});
```

### Polling Options

| Option         | Type     | Description                        | Default   |
| -------------- | -------- | ---------------------------------- | --------- |
| `pollInterval` | number   | Milliseconds between status checks | `5000`    |
| `maxWaitTime`  | number   | Maximum wait time in milliseconds  | `3600000` |
| `onProgress`   | function | Callback for progress updates      | undefined |

## Response Format

```typescript theme={null}
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>;  // Research output
  sources?: DeepResearchSource[];  // Sources used
  cost?: number;  // Fixed cost for the task
  cost_breakdown?: DeepResearchCostBreakdown;  // Itemized cost breakdown
  tools?: DeepResearchTools;  // Resolved tools configuration
  created_at?: string;  // ISO 8601 timestamp string
  completed_at?: string;  // ISO 8601 timestamp string
  pdf_url?: string;  // PDF download URL
  images?: ImageMetadata[];  // Generated images
  deliverables?: DeliverableResult[];  // Generated deliverable files
  batch_id?: string;  // Batch ID if task belongs to a batch
  batch_task_id?: string;  // Batch task identifier if task belongs to a batch
  error?: string;  // Error message if failed
}
```

### Source Object

```typescript theme={null}
interface DeepResearchSource {
  title: string;
  url: string;
  snippet?: string;
  source?: string;  // web, pubmed, arxiv, etc.
  word_count?: number;
  doi?: string;  // For academic papers
}
```

### Cost

The `cost` field contains the total price for the task (base mode price + any tool surcharges). The `cost_breakdown` field provides an itemized breakdown:

```typescript theme={null}
if (result.cost_breakdown) {
  console.log(`Total: $${result.cost}`);
  console.log(`  Base: $${result.cost_breakdown.task}`);
  if (result.cost_breakdown.screenshots) {
    console.log(`  Screenshots: $${result.cost_breakdown.screenshots}`);
  }
  if (result.cost_breakdown.code_execution) {
    console.log(`  Code execution: $${result.cost_breakdown.code_execution}`);
  }
  if (result.cost_breakdown.deliverables) {
    console.log(`  Deliverables: $${result.cost_breakdown.deliverables}`);
  }
}
```

## Task Management

### Check Status

```typescript theme={null}
const status = await valyu.deepresearch.status(taskId);

console.log(`Status: ${status.status}`);
if (status.progress) {
  console.log(`Step ${status.progress.current_step}/${status.progress.total_steps}`);
}
```

### Get Assets

Retrieve authenticated assets (images, charts, deliverables, PDFs) from completed tasks. Supports both API key authentication (default) and token-based authentication.

```typescript theme={null}
// Using API key (default)
const asset = await valyu.deepresearch.getAssets(taskId, assetId);

if (asset.success && asset.data) {
  // asset.data is a Buffer containing the binary data
  // asset.contentType contains the MIME type (e.g., "image/png", "application/pdf")
  fs.writeFileSync("output.png", asset.data);
}

// Using token
const asset = await valyu.deepresearch.getAssets(taskId, assetId, {
  token: "asset-access-token"
});
```

**Response:**

```typescript theme={null}
interface DeepResearchGetAssetsResponse {
  success: boolean;
  data?: Buffer;  // Binary asset data
  contentType?: string;  // MIME type (e.g., "image/png", "application/pdf")
  error?: string;
}
```

### Toggle Public

## togglePublic()

Toggle public access for a completed DeepResearch task.

```typescript theme={null}
const result = await valyu.deepresearch.togglePublic("dr_abc123", true);
console.log(result.public); // true
```

### Parameters

| Parameter  | Type      | Description                                  | Default  |
| ---------- | --------- | -------------------------------------------- | -------- |
| `taskId`   | `string`  | The DeepResearch task ID                     | Required |
| `isPublic` | `boolean` | Whether to make the task publicly accessible | Required |

### Response

| Field             | Type      | Description                     |
| ----------------- | --------- | ------------------------------- |
| `success`         | `boolean` | Whether the operation succeeded |
| `deepresearch_id` | `string`  | The task ID                     |
| `public`          | `boolean` | Current public status           |
| `message`         | `string`  | Status message                  |

### Add Follow-up Instructions

Add instructions to refine or adjust the scope of a running task. Instructions are collected during the research phase and incorporated when report generation begins.

<Warning>
  Follow-up instructions can only be added **before the writing phase starts**. Once research completes and the writing phase begins, new instructions are rejected.
</Warning>

```typescript theme={null}
// Add first instruction
const response = await valyu.deepresearch.update(
  taskId,
  "Focus more on peer-reviewed sources from 2024"
);

if (response.success) {
  console.log("Instruction added");
}

// Add another instruction
await valyu.deepresearch.update(
  taskId,
  "Include a comparison table of major providers"
);
```

### Respond to HITL checkpoint

When a task is in `awaiting_input` or `paused` status, respond to the checkpoint:

```typescript theme={null}
const result = await client.deepresearch.respond(
  "dr_abc123",
  status.interaction!.interaction_id,
  { approved: true }
);
console.log(result.status); // "running" or "queued"
```

### Cancel a Task

```typescript theme={null}
const response = await valyu.deepresearch.cancel(taskId);

if (response.success) {
  console.log("Task cancelled");
}
```

### Delete a Task

```typescript theme={null}
const response = await valyu.deepresearch.delete(taskId);

if (response.success) {
  console.log("Task deleted");
}
```

### List All Tasks

```typescript theme={null}
const tasks = await valyu.deepresearch.list({ limit: 50 });

tasks.data?.forEach(task => {
  console.log(`${task.query?.substring(0, 50)}... - ${task.status}`);
});
```

## Webhooks

Get notified when research completes instead of polling. See the [DeepResearch Guide](/guides/deepresearch#webhooks) for complete webhook documentation including signature verification and retry behavior.

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Research market trends in AI",
  webhookUrl: "https://your-app.com/webhooks/deepresearch"
});

// IMPORTANT: Save the secret immediately - it's only returned once
const webhookSecret = task.webhook_secret;
```

<Warning>
  The `webhook_secret` is only returned once. Store it securely—you cannot retrieve it later.
</Warning>

## Error Handling

```typescript theme={null}
const task = await valyu.deepresearch.create({
  query: "Research query"
});

if (!task.success) {
  console.error(`Failed to create task: ${task.error}`);
  return;
}

try {
  const result = await valyu.deepresearch.wait(task.deepresearch_id!, {
    maxWaitTime: 1800000  // 30 minutes for standard, use 7200000 for heavy
  });
  
  if (result.status === "completed") {
    console.log(result.output);
  } else if (result.status === "failed") {
    console.error(`Research failed: ${result.error}`);
  }
  
} catch (error: any) {
  if (error.message.includes("Maximum wait time")) {
    console.log("Task timed out - cancelling");
    await valyu.deepresearch.cancel(task.deepresearch_id!);
  } else {
    console.error(`Task error: ${error.message}`);
  }
}
```

## Best Practices

See the [DeepResearch Guide](/guides/deepresearch#best-practices) for comprehensive best practices including polling strategies, timeouts, and research quality tips.

| Mode       | Recommended Poll Interval | Recommended Timeout |
| ---------- | ------------------------- | ------------------- |
| `fast`     | 2-5 seconds               | 10 minutes          |
| `standard` | 5-10 seconds              | 30 minutes          |
| `heavy`    | 10-30 seconds             | 120 minutes         |
| `max`      | 30-60 seconds             | 180 minutes         |

```typescript theme={null}
// Production: use webhooks instead of polling
const task = await valyu.deepresearch.create({
  query: "Research query",
  webhookUrl: "https://your-app.com/webhooks"
});
```

### Type-Safe Structured Output

```typescript theme={null}
interface ResearchOutput {
  summary: string;
  key_findings: string[];
  recommendations: string[];
}

const result = await valyu.deepresearch.wait(taskId);

if (result.output_type === "json" && result.output) {
  const data = result.output as ResearchOutput;
  console.log(data.summary);
  data.key_findings.forEach(finding => console.log(`- ${finding}`));
}
```

## See Also

<CardGroup cols={2}>
  <Card title="DeepResearch Guide" icon="book" href="/guides/deepresearch">
    Complete guide with search config, webhooks, and use cases
  </Card>

  <Card title="Batch Processing" icon="layer-group" href="/sdk/typescript-sdk/deepresearch-batch">
    Process multiple research tasks in parallel
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python-sdk/deepresearch">
    Python SDK reference
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/deepresearch-create">
    REST API endpoint documentation
  </Card>
</CardGroup>