> ## 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 Quickstart

> Get started with async deep research in minutes

DeepResearch performs comprehensive research by searching multiple sources, analyzing content, and generating detailed reports. Tasks run asynchronously in the background, enabling thorough multi-step research that can take minutes to complete.

## What You Can Do

* **In-depth research** - Complex analysis across web, academic, and proprietary sources
* **Report generation** - Get markdown or PDF reports with citations
* **Structured data** - Extract research results in custom JSON formats
* **Background processing** - Long-running research without blocking your application

## Features

<CardGroup cols={2}>
  <Card title="Multi-Source Research" icon="magnifying-glass" href="/guides/deepresearch#search-configuration">
    Searches web, academic, and proprietary sources in a single task.
  </Card>

  <Card title="Research Modes" icon="gauge" href="/guides/deepresearch#research-modes">
    Choose fast for quick answers, standard for balanced research, heavy for complex analysis with fact verification, or max for exhaustive research.
  </Card>

  <Card title="Multiple Outputs" icon="file-lines" href="/guides/deepresearch#output-formats">
    Get results as markdown, PDF, or structured JSON.
  </Card>

  <Card title="File Analysis" icon="file-pdf" href="/guides/deepresearch#file-attachments">
    Attach PDFs, images, and documents for analysis.
  </Card>
</CardGroup>

## Getting Started

### Create a Research Task

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()

  # Create a research task
  task = valyu.deepresearch.create(
      query="What are the key differences between RAG and fine-tuning for LLMs?",
      mode="standard"
  )

  print(f"Task created: {task.deepresearch_id}")
  print(f"Status: {task.status}")
  ```

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

  console.log(`Task created: ${task.deepresearch_id}`);
  console.log(`Status: ${task.status}`);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.valyu.ai/v1/deepresearch/tasks" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "query": "What are the key differences between RAG and fine-tuning for LLMs?",
      "mode": "standard"
    }'
  ```
</CodeGroup>

### Wait for Completion

<CodeGroup>
  ```python Python theme={null}
  # Wait for the task to complete
  result = valyu.deepresearch.wait(
      task.deepresearch_id,
      poll_interval=5,      # Check every 5 seconds
      max_wait_time=1800    # Timeout after 30 minutes (standard mode)
  )

  if result.status == "completed":
      print("Research completed!")
      print(result.output)
      
      # Access sources used
      for source in result.sources:
          print(f"- {source.title}: {source.url}")
      
      # Check cost
      print(f"Cost: ${result.cost}")
  ```

  ```typescript TypeScript theme={null}
  // Wait for the task to complete
  const result = await valyu.deepresearch.wait(task.deepresearch_id, {
    pollInterval: 5000,    // Check every 5 seconds
    maxWaitTime: 1800000   // Timeout after 30 minutes (standard mode)
  });

  if (result.status === "completed") {
    console.log("Research completed!");
    console.log(result.output);
    
    // Access sources used
    result.sources?.forEach(source => {
      console.log(`- ${source.title}: ${source.url}`);
    });
    
    // Check cost
    console.log(`Cost: $${result.cost}`);
  }
  ```
</CodeGroup>

### Research Modes

Choose the right mode for your use case:

| 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 with fact verification | Up to \~90 minutes      |
| `max`      | Exhaustive research with maximum quality and fact verification                 | Up to \~180 minutes     |

<CodeGroup>
  ```python Python theme={null}
  # Fast mode for quick lookups
  task = valyu.deepresearch.create(
      query="What is quantum computing?",
      mode="fast"
  )

  # Heavy mode for complex research
  task = valyu.deepresearch.create(
      query="Analyze the competitive landscape of cloud computing in 2024",
      mode="heavy"
  )

  # Max mode for exhaustive research
  task = valyu.deepresearch.create(
      query="Comprehensive analysis of AI safety research with fact verification",
      mode="max"
  )
  ```

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

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

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

### Output Formats

#### Markdown (Default)

<CodeGroup>
  ```python Python theme={null}
  task = valyu.deepresearch.create(
      query="Explain quantum computing advancements",
      output_formats=["markdown"]
  )
  ```

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

#### Markdown + PDF

<CodeGroup>
  ```python Python theme={null}
  task = valyu.deepresearch.create(
      query="Write a report on renewable energy trends",
      output_formats=["markdown", "pdf"]
  )

  # After completion, access the PDF URL
  result = valyu.deepresearch.wait(task.deepresearch_id)
  if result.pdf_url:
      print(f"PDF available at: {result.pdf_url}")
  ```

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

  // After completion, access the PDF URL
  const result = await valyu.deepresearch.wait(task.deepresearch_id);
  if (result.pdf_url) {
    console.log(`PDF available at: ${result.pdf_url}`);
  }
  ```
</CodeGroup>

### Check Task Status

<CodeGroup>
  ```python Python theme={null}
  status = valyu.deepresearch.status(task_id)

  print(f"Status: {status.status}")
  if status.progress:
      print(f"Progress: {status.progress.current_step}/{status.progress.total_steps}")
  ```

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

  console.log(`Status: ${status.status}`);
  if (status.progress) {
    console.log(`Progress: ${status.progress.current_step}/${status.progress.total_steps}`);
  }
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Complete Guide" icon="book" href="/guides/deepresearch">
    Comprehensive documentation with all features and examples
  </Card>

  <Card title="Batch Processing" icon="layer-group" href="/guides/deepresearch-batching">
    Process multiple research tasks efficiently with shared configuration
  </Card>

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

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