Skip to main content
GET
/
v1
/
deepresearch
/
tasks
/
{id}
/
status
Get DeepResearch task status and results
curl --request GET \
  --url https://api.valyu.ai/v1/deepresearch/tasks/{id}/status \
  --header 'X-API-Key: <api-key>'
{
  "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "query": "Comprehensive analysis of CRISPR gene therapy clinical trials",
  "mode": "standard",
  "output_formats": [
    "markdown",
    "pdf"
  ],
  "created_at": "2024-06-15T10:30:00.000Z",
  "public": false,
  "progress": {
    "current_step": 5,
    "total_steps": 15
  }
}

Authorizations

​
X-API-Key
string
header
required

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

Path Parameters

​
id
string
required

DeepResearch task ID.

Response

Task status and results.

Full status and results of a DeepResearch task.

​
deepresearch_id
string
required

Unique identifier for the research task.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
status
enum<string>
required

Current task status.

  • queued - Waiting for capacity
  • running - Research in progress
  • completed - Research finished successfully
  • failed - Research failed
  • cancelled - Task was cancelled
Available options:
queued,
running,
completed,
failed,
cancelled
Example:

"completed"

​
query
string
required

The original research query.

Example:

"Comprehensive analysis of CRISPR gene therapy clinical trials"

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

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

Output formats requested for this task.

Available options:
markdown,
pdf,
toon
Example:
["markdown", "pdf"]
​
public
boolean

Whether the task results are publicly accessible.

Example:

false

​
batch_id
string

Batch ID if this task belongs to a batch.

​
batch_task_id
string

User-provided task ID within a batch.

​
progress
object

Research progress. Present when status is "running".

​
output_type
enum<string>

Format of the output. Present when status is "completed".

Available options:
markdown,
json,
toon
Example:

"markdown"

​
output

Research output. Markdown string or JSON object depending on output_type. Present when status is "completed" (may be partial on "failed" or "cancelled").

​
sources
object[]

Sources used during research. Present when status is "completed", "failed", or "cancelled".

​
cost
number

Total cost billed for this task in USD. Fixed per mode: $0.10 (fast), $0.50 (standard), $2.50 (heavy), $15.00 (max).

Example:

0.5

​
completed_at
string<date-time>

ISO 8601 timestamp of task completion. Present when status is "completed".

Example:

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

​
pdf_url
string<uri>

URL to the generated PDF report. Present when "pdf" was in output_formats.

​
images
object[]

Images generated during research (charts, AI-generated). Present when status is "completed".

​
deliverables
object[]

Generated deliverable files (CSV, Excel, PowerPoint, Word, PDF). Present when deliverables were requested.

​
messages
object[]

Conversation trace of the research agent. Present when status is "running" or "completed".

​
error
string

Error message. Present when status is "failed".