List Research Tasks
Lists the research tasks a knowledge base holds for the calling API key, newest first.
Tasks created with another key, or from Dify, never appear.
There is no stage or date filter. Keep the id from each Create Research Task response to follow the tasks that are still running.
For the plan, create, poll, and read flow, see Run a Research Task.
curl --request GET \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks \
--header 'Authorization: Bearer <token>'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks', 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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"budget_usd": 1.5,
"completed_at": 1788681642000,
"cost": {
"budgetUsd": 1.5,
"entries": [
{
"costUsd": 0.0011,
"provider": "openai",
"recordedAt": 1788681603000,
"step": "research.plan",
"usage": {
"completionTokens": 58,
"estimated": false,
"promptTokens": 310,
"researchModelCallId": "attempt:1:call-1",
"reserved": false,
"status": "succeeded",
"totalTokens": 368
}
},
{
"costUsd": 0.0124,
"provider": "openai",
"recordedAt": 1788681641000,
"step": "query.answer",
"usage": {
"completionTokens": 412,
"estimated": false,
"promptTokens": 3180,
"researchModelCallId": "attempt:1:call-2",
"reserved": false,
"status": "succeeded",
"totalTokens": 3592
}
}
],
"totalUsd": 0.0135
},
"created_at": 1788681600000,
"error": null,
"failure": null,
"id": "e4d1b7a2-3c5f-4d8e-9a0b-1c2d3e4f5a6b",
"knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
"limits": {
"max_retrieval_steps": 8,
"max_scanned_resources": 800,
"max_tool_calls": 12,
"timeout_ms": 120000
},
"metadata": {
"client_request_id": "client-20260907-0001",
"ticket": "SUP-1042"
},
"mode": "research",
"query": "What changed in the 2025 refund policy, and which regions are affected?",
"stage": "completed",
"top_k": 10,
"updated_at": 1788681642000
},
{
"budget_usd": null,
"completed_at": 1788678090000,
"cost": {
"entries": [
{
"costUsd": 0.0009,
"provider": "openai",
"recordedAt": 1788678003000,
"step": "graph.plan",
"usage": {
"completionTokens": 44,
"estimated": false,
"promptTokens": 260,
"researchModelCallId": "attempt:1:call-3",
"reserved": false,
"status": "succeeded",
"totalTokens": 304
}
}
],
"totalUsd": 0.0009
},
"created_at": 1788678000000,
"error": "RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"failure": {
"action": "retry",
"category": "dependency",
"code": "RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"message": "A service required by Agent Knowledge Base is temporarily unavailable.",
"parameters": null,
"retryPolicy": "manual",
"stage": "research",
"traceId": "0a9b8c7d-6e5f-4a4b-9c3d-2e1f0a9b8c7d"
},
"id": "0a9b8c7d-6e5f-4a4b-9c3d-2e1f0a9b8c7d",
"knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
"limits": null,
"metadata": {},
"mode": "deep",
"query": "Which suppliers are named in the 2024 audit findings?",
"stage": "failed",
"top_k": 10,
"updated_at": 1788678090000
}
],
"next_cursor": null
}Authorizations
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path Parameters
Query Parameters
Response
One page of research tasks.
Research tasks, newest first. Each item is the same object as Get Research Task. The answer is not on it.
Show child attributes
Show child attributes
Was this page helpful?
curl --request GET \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks \
--header 'Authorization: Bearer <token>'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks', 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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"budget_usd": 1.5,
"completed_at": 1788681642000,
"cost": {
"budgetUsd": 1.5,
"entries": [
{
"costUsd": 0.0011,
"provider": "openai",
"recordedAt": 1788681603000,
"step": "research.plan",
"usage": {
"completionTokens": 58,
"estimated": false,
"promptTokens": 310,
"researchModelCallId": "attempt:1:call-1",
"reserved": false,
"status": "succeeded",
"totalTokens": 368
}
},
{
"costUsd": 0.0124,
"provider": "openai",
"recordedAt": 1788681641000,
"step": "query.answer",
"usage": {
"completionTokens": 412,
"estimated": false,
"promptTokens": 3180,
"researchModelCallId": "attempt:1:call-2",
"reserved": false,
"status": "succeeded",
"totalTokens": 3592
}
}
],
"totalUsd": 0.0135
},
"created_at": 1788681600000,
"error": null,
"failure": null,
"id": "e4d1b7a2-3c5f-4d8e-9a0b-1c2d3e4f5a6b",
"knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
"limits": {
"max_retrieval_steps": 8,
"max_scanned_resources": 800,
"max_tool_calls": 12,
"timeout_ms": 120000
},
"metadata": {
"client_request_id": "client-20260907-0001",
"ticket": "SUP-1042"
},
"mode": "research",
"query": "What changed in the 2025 refund policy, and which regions are affected?",
"stage": "completed",
"top_k": 10,
"updated_at": 1788681642000
},
{
"budget_usd": null,
"completed_at": 1788678090000,
"cost": {
"entries": [
{
"costUsd": 0.0009,
"provider": "openai",
"recordedAt": 1788678003000,
"step": "graph.plan",
"usage": {
"completionTokens": 44,
"estimated": false,
"promptTokens": 260,
"researchModelCallId": "attempt:1:call-3",
"reserved": false,
"status": "succeeded",
"totalTokens": 304
}
}
],
"totalUsd": 0.0009
},
"created_at": 1788678000000,
"error": "RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"failure": {
"action": "retry",
"category": "dependency",
"code": "RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED",
"message": "A service required by Agent Knowledge Base is temporarily unavailable.",
"parameters": null,
"retryPolicy": "manual",
"stage": "research",
"traceId": "0a9b8c7d-6e5f-4a4b-9c3d-2e1f0a9b8c7d"
},
"id": "0a9b8c7d-6e5f-4a4b-9c3d-2e1f0a9b8c7d",
"knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
"limits": null,
"metadata": {},
"mode": "deep",
"query": "Which suppliers are named in the 2024 audit findings?",
"stage": "failed",
"top_k": 10,
"updated_at": 1788678090000
}
],
"next_cursor": null
}