DeepResearch

Get DeepResearch task status and results

Retrieve the current status, progress, and results of a DeepResearch task. Poll this endpoint to track research progress and retrieve the final output.

get/v1/deepresearch/tasks/{id}/status

Request

Base URL: https://api.valyu.ai
URL: https://api.valyu.ai/v1/deepresearch/tasks/{id}/status
Auth: API key in header X-API-Key

Path parameters

idstring required

DeepResearch task ID.

Response

Task status and results.

deepresearch_idstring required

Unique identifier for the research task.

Current task status.

queued - Waiting for capacity
running - Research in progress
awaiting_input - HITL checkpoint active, waiting for user response
paused - HITL checkpoint timed out, state saved, respond anytime to resume
completed - Research finished successfully
failed - Research failed
cancelled - Task was cancelled

querystring required

The original research query.

mode'fast' | 'standard' | 'heavy' | 'max' required

Research mode used for this task.

created_atstring date-time required

ISO 8601 timestamp of task creation.

publicboolean

Whether the task results are publicly accessible.

batch_idstring

Batch ID if this task belongs to a batch.

batch_task_idstring

User-provided task ID within a batch.

output_type'markdown' | 'json' | 'toon'

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

costnumber

Total cost billed for this task in USD (base mode price + any tool surcharges).

completed_atstring date-time

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

pdf_urlstring uri

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

errorstring

Error message. Present when status is "failed".

Example response

{
  "deepresearch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "query": "Comprehensive analysis of CRISPR gene therapy clinical trials",
  "mode": "standard",
  "output_formats": [
    "markdown",
    "pdf"
  ],
  "created_at": "2024-06-15T10:30:00.000Z",
  "progress": {
    "current_step": 5,
    "total_steps": 15
  },
  "output_type": "markdown",
  "sources": [
    {
      "title": "CRISPR Gene Therapy: A Comprehensive Review",
      "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
      "fragment": "#:~:text=Revenue%20grew%2040%25%20to%20%245.2B"
    }
  ],
  "cost": 0.5,
  "completed_at": "2024-06-15T10:35:00.000Z",
  "images": [
    {
      "image_id": "img_a1b2c3d4e5f6",
      "image_type": "chart",
      "title": "Clinical Trial Phase Distribution",
      "description": "Bar chart showing distribution of CRISPR trials across phases",
      "image_url": "https://storage.valyu.ai/images/img_a1b2c3d4e5f6.png",
      "created_at": 1718444520000,
      "source_url": "https://example.com/dashboard",
      "captured_at": 1718444520000,
      "chart_type": "bar",
      "x_axis_label": "Trial Phase",
      "y_axis_label": "Number of Trials"
    }
  ],
  "deliverables": [
    {
      "id": "del_a1b2c3d4e5f6",
      "request": "Extract all company names, founding years, and revenue data into a spreadsheet",
      "type": "xlsx",
      "status": "completed",
      "title": "company_data.xlsx",
      "description": "Spreadsheet containing 25 companies with founding years and revenue data",
      "url": "https://storage.valyu.ai/deliverables/del_a1b2c3d4e5f6.xlsx?token=...",
      "s3_key": "deliverables/org_123/del_a1b2c3d4e5f6.xlsx",
      "row_count": 25,
      "column_count": 5,
      "created_at": 1718444640000
    }
  ],
  "interaction": {
    "data": {
      "questions": [
        {
          "question": "What geographic regions should the research focus on?",
          "context": "The query mentions global markets — narrowing scope improves depth"
        }
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.