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": "What are the latest developments in quantum computing?",
  "mode": "standard"
}
'
{
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "running",
  "mode": "standard",
  "created_at": "2025-01-15T10:30:00.000Z",
  "metadata": {},
  "public": false,
  "webhook_secret": "a1b2c3d4e5f6..."
}

Authorizations

​
x-api-key
string
header
required

Your Valyu API key. Get one at platform.valyu.ai

Body

application/json
​
query
string
required

Research query or task description

Example:

"What are the key differences between RAG and fine-tuning for LLMs?"

​
mode
enum<string>
default:standard

DeepResearch mode:

  • fast: Ideal for quicker answers and lightweight research. Typically completes in ~2–5 minutes.
  • standard: A balanced option for deeper insights without long wait times. Runs for ~10–20 minutes.
  • heavy: Designed for in-depth, long-running research tasks. Can run for up to ~90 minutes.
Available options:
fast,
standard,
heavy
Example:

"standard"

​
model
enum<string>
default:standard

DeepResearch mode (deprecated, use 'mode' instead)

Available options:
fast,
standard,
heavy
Example:

"standard"

​
output_formats
(enum<string> | object)[]

Output formats. Use ['markdown'], ['markdown', 'pdf'], or a JSON schema object for structured output. Cannot mix JSON schema with markdown/pdf.

Available options:
markdown,
pdf,
toon
Example:
["markdown"]
​
strategy
string | null

Natural language strategy instructions prepended to the system prompt

Example:

"Focus on peer-reviewed sources and recent publications"

​
search
object

Search configuration parameters

​
urls
string<uri>[]

URLs to extract content from (max 10)

Maximum array length: 10
Example:
["https://example.com/article"]
​
files
object[]

File attachments (PDFs, images, documents). Max 10 files.

Maximum array length: 10
​
mcp_servers
object[]

MCP server configurations for custom tools (max 5 servers)

Maximum array length: 5
​
code_execution
boolean
default:true

Enable/disable code execution during research

​
previous_reports
string[]

Previous deep research IDs to use as context (max 3)

Maximum array length: 3
​
webhook_url
string<uri>

HTTPS URL for webhook notifications. When provided, Valyu will POST the full task result to this URL when the task completes or fails. The request includes X-Webhook-Signature and X-Webhook-Timestamp headers for verification. HTTP URLs are rejected—only HTTPS is supported.

​
metadata
object

Custom metadata for tracking

​
deliverables
(string | object)[]

Additional file outputs to generate from the research (CSV, Excel, PowerPoint, Word, PDF). Max 10 deliverables.

Maximum array length: 10

Simple deliverable description (e.g., 'Excel file with company data')

Example:
[
  {
    "type": "xlsx",
    "description": "Extract all company names, founding years, and revenue data into a spreadsheet"
  }
]

Response

Task created successfully

​
deepresearch_id
string<uuid>

Unique task identifier

Example:

"f992a8ab-4c91-4322-905f-190107bd5a5b"

​
status
enum<string>

Current task status

Available options:
queued,
running,
completed,
failed,
cancelled
​
mode
enum<string>

Research mode used

Available options:
fast,
standard,
heavy
​
model
enum<string>

Research mode used (deprecated, use 'mode' instead)

Available options:
fast,
standard,
heavy
​
created_at
string<date-time>

Task creation timestamp

​
metadata
object

Custom metadata provided with the request

​
public
boolean

Whether the task is publicly accessible

​
webhook_secret
string

32-byte cryptographic secret (64-character hex string) for verifying webhook signatures. Only returned once in the creation response—store it securely. Use this secret to verify the HMAC-SHA256 signature in the X-Webhook-Signature header of incoming webhook requests.

​
message
string

Additional status message (e.g., if queued)