Create a DeepResearch task - POST /v1/deepresearch/tasks

curl --request POST \
  --url https://api.valyu.ai/v1/deepresearch/tasks \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "Comprehensive analysis of CRISPR gene therapy clinical trials in 2024",
  "mode": "standard"
}
'

{
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "running",
  "mode": "standard",
  "created_at": "2024-06-15T10:30:00.000Z",
  "metadata": {
    "project": "drug-discovery"
  },
  "public": false
}

POST

deepresearch

tasks

curl --request POST \
  --url https://api.valyu.ai/v1/deepresearch/tasks \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "Comprehensive analysis of CRISPR gene therapy clinical trials in 2024",
  "mode": "standard"
}
'

{
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "running",
  "mode": "standard",
  "created_at": "2024-06-15T10:30:00.000Z",
  "metadata": {
    "project": "drug-discovery"
  },
  "public": false
}

Run a multi-step investigation and receive a cited report. Provide a focused question, the intended audience and the evidence or comparisons the report needs to cover.

Start, store and retrieve

Create a task and store its deepresearch_id in your application.
Poll Get status, or configure a completion webhook.
When status is completed, read output, sources and any requested deliverables.
Handle failed and cancelled separately from successful completion. If checkpoints are enabled, handle awaiting_input and paused too.

Use research_strategy to guide investigation and report_format to describe presentation. Choose output_formats for machine-readable output, or request deliverables for files. Report instructions express the requested result; validate the returned output before inserting it into a downstream workflow. For repeatable tasks, run a Workflow with workflow_id and workflow_params instead of freeform query fields.

Modes and billing

Mode	Credits per task
`instant`	8
`fast`	25
`standard`	100
`heavy`	500
`max`	2,500

Tool add-ons (screenshots, code execution, browser use, extra deliverables) are charged on top; see pricing. When you create a task, its mode price is held against your balance until the task is charged. If your balance, minus amounts held for your other queued and running tasks, can’t cover it, the request returns 402 with an Insufficient credits error and no task is created. A 503 with Billing temporarily unavailable means billing couldn’t be checked; no task was created, so retry with backoff. Failed tasks are free. Cancelling a running or awaiting_input task charges the full mode price; cancelling a queued or paused task is free.

Authorizations

X-API-Key

string

header

required

API key for authentication. Get yours at platform.valyu.ai.

Body

application/json

Option 1
Option 2
Option 3

Request to create a DeepResearch task.

A task can be either freeform (provide query/input plus optional research_strategy, report_format, etc.) or workflow-driven (provide workflow_id + workflow_params). The two modes are mutually exclusive: passing workflow_id alongside freeform fields (query, input, research_strategy, report_format) returns 400 workflow_and_freeform_mutually_exclusive. When running a workflow, any mode/deliverables/tools you pass in the body override the template defaults.

query

string

required

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

Maximum string length: 25000

Example:

"Comprehensive analysis of CRISPR gene therapy clinical trials in 2024"

input

string

deprecated

Deprecated. Use query instead.

workflow_id

string

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.

Example:

"ib-company-profile"

workflow_params

object

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.

Show child attributes

Example:

{ "company": "NVIDIA (NVDA)" }

workflow_version

integer

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.

Required range: x >= 1

Example:

1

mode

enum<string>

default:standard

Research mode controlling depth and cost. Prices are credits per task; tool add-ons are extra. See pricing.

Mode	Credits	Best For	Max Steps
`instant`	8	Short, cited answers in under 30 seconds	1
`fast`	25	Quick queries, batch processing	12
`standard`	100	Balanced research	25
`heavy`	500	Complex topics requiring deep analysis	45
`max`	2,500	Larger research budget for complex tasks	75

Available options:

instant,

fast,

standard,

heavy,

max

Example:

"standard"

model

enum<string>

deprecated

Deprecated. Use mode instead.

Available options:

fast,

standard,

heavy,

max

strategy

string

deprecated

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

Example:

"Focus on Phase 3 trials and compare efficacy data across studies"

research_strategy

string

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.

Maximum string length: 15000

Example:

"Focus on Phase 3 trials and compare efficacy data across studies"

report_format

string

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.

Maximum string length: 15000

Example:

"Write a 2-page executive summary with bullet points and a comparison table"

object

Search configuration for DeepResearch tasks.

Show child attributes

urls

string<uri>[]

URLs to include in the research context. Max 10.

Maximum array length: 10

Example:

["https://example.com/selected-trial-record"]

files

object[]

Files to analyze as part of the research. Max 10.

Maximum array length: 10

Show child attributes

output_formats

(enum<string> | object)[]

Desired output formats. Defaults to ["markdown"].

"markdown" - Markdown report (default)
"pdf" - PDF document (can combine with "markdown")
"toon" - Token-efficient structured output; requires a JSON Schema object to also be supplied
JSON Schema object - Structured JSON output

A JSON Schema object cannot be combined with "markdown" or "pdf". "toon" requires a JSON Schema object.

Available options:

markdown,

pdf,

toon

Example:

["markdown", "pdf"]

metadata

object

Arbitrary key-value metadata to attach to the task.

Show child attributes

Example:

{
  "project": "drug-discovery",
  "priority": "high"
}

mcp_servers

object[]

MCP servers to provide additional tools during research. Max 5.

Maximum array length: 5

Show child attributes

code_execution

boolean

default:false

deprecated

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

tools

object

Controls which optional tools the research agent can use. Each tool accepts an object with enabled (boolean, default true) and optional max_calls (integer, capped at system default).

Show child attributes

previous_reports

string[]

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

Maximum array length: 3

Example:

["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]

webhook_url

string<uri>

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

Example:

"https://example.com/webhooks/deepresearch"

alert_email

Email notification on completion. Pass a string (email address) or an object with email and optional custom_url. The custom_url must contain {id} which gets replaced with the task ID. Email must belong to your organization.

deliverables

(string | object)[]

Deliverable files to generate from the research (e.g. Excel reports, presentations). Max 10.

Maximum array length: 10

A deliverable to generate from the research. Can be a string (natural language description, max 500 chars) or a structured object.

Maximum string length: 500

hitl

object

Human-in-the-loop configuration. Enable checkpoints that pause execution at key decision points. Not available for batch requests.

Show child attributes

Response

Research task created and queued.

Response after creating a DeepResearch task.

deepresearch_id

string

required

Unique identifier for the research task.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

status

enum<string>

required

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

Available options:

running,

queued

Example:

"running"

mode

enum<string>

required

Research mode used for this task.

Available options:

fast,

standard,

heavy,

max

Example:

"standard"

created_at

string<date-time>

required

ISO 8601 timestamp of task creation.

Example:

"2024-06-15T10:30:00.000Z"

metadata

object

Metadata attached to the task.

public

boolean

Whether the task is publicly accessible.

Example:

false

webhook_secret

string

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

message

string

Status message. Present when task is queued.

API essentials

Search

Contents

Answer

DeepResearch

DeepResearch (Batch)

Workflows

Datasources

Create Task

Start, store and retrieve

Modes and billing

Authorizations

Body

Response

​Start, store and retrieve

​Modes and billing

Authorizations

Body

Response

Start, store and retrieve

Modes and billing