Research Tasks
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.
GET
/
knowledge-fs
/
spaces
/
{knowledge_base_id}
/
research-tasks
List Research Tasks
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
Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.
Query Parameters
Cursor from the previous page's next_cursor.
Required string length:
1 - 1000Tasks per page.
Required range:
1 <= x <= 100Response
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
Cursor for the next page, or null on the last page. Send it back as cursor.
Was this page helpful?
⌘I
List Research Tasks
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
}