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.

​
query
string
required

The research query or question. Use query (preferred) or input (deprecated).

Example:

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

​
input
string
deprecated

Deprecated. Use query instead.

​
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.

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.

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" - Visual toon-style output
  • JSON Schema object - Structured JSON output

JSON schema output cannot be combined with markdown or PDF.

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:true

Enable code execution capability for the research agent.

​
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

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.