curl --request GET \
--url https://api.valyu.ai/v1/deepresearch/tasks/{id}/status \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.valyu.ai/v1/deepresearch/tasks/{id}/status"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.valyu.ai/v1/deepresearch/tasks/{id}/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.valyu.ai/v1/deepresearch/tasks/{id}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.valyu.ai/v1/deepresearch/tasks/{id}/status"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.valyu.ai/v1/deepresearch/tasks/{id}/status")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valyu.ai/v1/deepresearch/tasks/{id}/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_bodyGet Status
Reference for getting deep research task status via GET /v1/deepresearch/tasks/{id}/status.
curl --request GET \
--url https://api.valyu.ai/v1/deepresearch/tasks/{id}/status \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.valyu.ai/v1/deepresearch/tasks/{id}/status"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.valyu.ai/v1/deepresearch/tasks/{id}/status', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.valyu.ai/v1/deepresearch/tasks/{id}/status",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.valyu.ai/v1/deepresearch/tasks/{id}/status"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.valyu.ai/v1/deepresearch/tasks/{id}/status")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valyu.ai/v1/deepresearch/tasks/{id}/status")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_bodydeepresearch_id returned when you created the task.
Handle the lifecycle
| Status | Application behavior |
|---|---|
queued, running | Show progress and poll again after a delay |
awaiting_input, paused | Display the interaction and submit a response |
completed | Read and validate output, sources and requested files |
failed, cancelled | Show the terminal state; do not present partial output as a completed report |
Authorizations
API key for authentication. Get yours at platform.valyu.ai.
Path Parameters
DeepResearch task ID.
Response
Task status and results.
Full status and results of a DeepResearch task.
Unique identifier for the research task.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Current task status.
queued- Waiting for capacityrunning- Research in progressawaiting_input- HITL checkpoint active, waiting for user responsepaused- HITL checkpoint timed out, state saved, respond anytime to resume (your balance must cover the task when it resumes)completed- Research finished successfullyfailed- Research failedcancelled- Task was cancelled
queued, running, awaiting_input, paused, completed, failed, cancelled "completed"
The original research query.
"Comprehensive analysis of CRISPR gene therapy clinical trials"
Research mode used for this task.
fast, standard, heavy, max "standard"
ISO 8601 timestamp of task creation.
"2024-06-15T10:30:00.000Z"
Short title for the task, when available.
Output formats requested for this task.
markdown, pdf, toon ["markdown", "pdf"]
Whether the task results are publicly accessible.
false
Metadata you attached when creating the task (or the batch task).
Batch ID if this task belongs to a batch.
User-provided task ID within a batch.
Research progress. Present when status is "running".
Show child attributes
Show child attributes
Format of the output. Present when status is "completed".
markdown, json, toon "markdown"
Research output. Markdown string or JSON object depending on output_type. Present when status is "completed" (may be partial on "failed" or "cancelled").
Word count of the report, when available.
Sources used during research. Present when status is "completed", "failed", or "cancelled".
Show child attributes
Show child attributes
Total cost billed for this task (base mode price + any tool surcharges). Failed tasks are not billed, even if this field is non-zero.
0.625
Itemized cost breakdown. Only present when the task has completed.
Show child attributes
Show child attributes
{ "task": 0.625 }
Resolved tools configuration for this task.
Show child attributes
Show child attributes
ISO 8601 timestamp of task completion. Present when status is "completed".
"2024-06-15T10:35:00.000Z"
URL to the generated PDF report. Present when "pdf" was in output_formats.
Images generated during research (charts, AI-generated, screenshots). Present when status is "completed".
Show child attributes
Show child attributes
Generated deliverable files (CSV, Excel, PowerPoint, Word, PDF). Present when deliverables were requested.
Show child attributes
Show child attributes
Conversation trace of the research agent. Present when status is "running" or "completed".
Show child attributes
Show child attributes
Error message. Present when status is "failed".
HITL configuration. Present when HITL was enabled on task creation.
Show child attributes
Show child attributes
Current HITL checkpoint. Present when status is awaiting_input or paused.
Show child attributes
Show child attributes
History of completed HITL checkpoints. Present after any checkpoint completes.
Show child attributes
Show child attributes
Was this page helpful?