DeepResearch

Create a DeepResearch task

Start an async research task that performs comprehensive, multi-step research. The research agent searches multiple sources, analyzes content, executes code, and generates a detailed report with citations.

Tasks run in the background and typically take 1-10 minutes depending on the mode. Poll the status endpoint or use webhooks to get results.

post/v1/deepresearch/tasks

Request

  • Base URL: https://api.valyu.ai
  • URL: https://api.valyu.ai/v1/deepresearch/tasks
  • Auth: API key in header X-API-Key

Request body

querystring required

The research query or question. Use query (preferred) or input (deprecated). Maximum 25,000 characters. Mutually exclusive with workflow_id.

inputstring

Deprecated. Use query instead.

workflow_idstring

Beta. Slug of a workflow to run instead of a freeform query. When set, the task is resolved from the workflow's prompt template using workflow_params. Mutually exclusive with freeform fields (query, input, research_strategy, report_format); supplying both returns 400 workflow_and_freeform_mutually_exclusive. See the Workflows endpoints.

workflow_paramsobject

Beta. Values for the workflow's template variables, keyed by variable key. Required when workflow_id is set. Values must satisfy the workflow's declared variable types and validation rules.

workflow_versioninteger

Beta. Pin the run to a specific immutable version of the workflow. Defaults to the workflow's current version when omitted. Only valid with workflow_id.

mode'fast' | 'standard' | 'heavy' | 'max'

Research mode controlling depth and cost.

ModePriceBest ForMax Steps
fast$0.10Quick queries, batch processing10
standard$0.50Balanced research15
heavy$2.50Complex topics requiring deep analysis15
max$15.00Exhaustive research with maximum quality25
model'fast' | 'standard' | 'heavy' | 'max'

Deprecated. Use mode instead.

strategystring

Deprecated. Use research_strategy instead. Natural language strategy to guide the research agent's approach.

research_strategystring

Natural language strategy to guide the research phase. Controls how the agent searches, what sources to prioritize, and research methodology. Combined length of research_strategy and report_format must not exceed 15,000 characters.

report_formatstring

Natural language instructions for the output format. Has highest priority and overrides default formatting. Controls structure, style, length, and presentation of the final report. Combined length of research_strategy and report_format must not exceed 15,000 characters.

urlsstring[]

URLs to include in the research context. Max 10.

metadataobject

Arbitrary key-value metadata to attach to the task.

code_executionboolean

Deprecated: use tools.code_execution instead. Enable code execution capability.

previous_reportsstring[]

DeepResearch task IDs to use as context for this task. Max 3.

webhook_urlstring uri

HTTPS URL to receive a webhook POST when the task completes. Signed with HMAC-SHA256.

Example request

{
  "query": "Comprehensive analysis of CRISPR gene therapy clinical trials in 2024",
  "workflow_id": "ib-company-profile",
  "workflow_params": {
    "company": "NVIDIA (NVDA)"
  },
  "workflow_version": 1,
  "mode": "standard",
  "strategy": "Focus on Phase 3 trials and compare efficacy data across studies",
  "research_strategy": "Focus on Phase 3 trials and compare efficacy data across studies",
  "report_format": "Write a 2-page executive summary with bullet points and a comparison table",
  "urls": [
    "https://clinicaltrials.gov/study/NCT12345678"
  ],
  "files": [
    {
      "data": "data:application/pdf;base64,JVBERi0xLjQK...",
      "filename": "research_paper.pdf",
      "mediaType": "application/pdf"
    }
  ],
  "output_formats": [
    "markdown",
    "pdf"
  ],
  "metadata": {
    "project": "drug-discovery",
    "priority": "high"
  },
  "mcp_servers": [
    {
      "url": "https://mcp.example.com/tools"
    }
  ],
  "previous_reports": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "webhook_url": "https://your-app.com/webhooks/deepresearch",
  "alert_email": {
    "custom_url": "https://your-app.com/reports/{id}"
  }
}

Response

Research task created and queued.

deepresearch_idstring required

Unique identifier for the research task.

status'running' | 'queued' required

Initial task status. "running" if started immediately, "queued" if waiting for capacity.

mode'fast' | 'standard' | 'heavy' | 'max' required

Research mode used for this task.

created_atstring date-time required

ISO 8601 timestamp of task creation.

metadataobject

Metadata attached to the task.

publicboolean

Whether the task is publicly accessible.

webhook_secretstring

HMAC-SHA256 secret for verifying webhook payloads. Only present when webhook_url was provided.

messagestring

Status message. Present when task is queued.

Example response

{
  "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "mode": "standard",
  "created_at": "2024-06-15T10:30:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.