Skip to main content
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
}

Authorizations

​
X-API-Key
string
header
required

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

Body

application/json

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.

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.

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
Available options:
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"

​
search
object

Search configuration for DeepResearch tasks.

​
urls
string<uri>[]

URLs to include in the research context. Max 10.

Maximum array length: 10
Example:
[
  "https://clinicaltrials.gov/study/NCT12345678"
]
​
files
object[]

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

Maximum array length: 10
​
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.

Example:
{
  "project": "drug-discovery",
  "priority": "high"
}
​
mcp_servers
object[]

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

Maximum array length: 5
​
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).

​
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://your-app.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.

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.