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.
1 min read
get/knowledge-fs/spaces/{knowledge_base_id}/research-tasks
Request example
curl --request GET \
--url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
headers = {
"Authorization": "Bearer <token>",
}
response = requests.request("GET", url, headers=headers)
print(response.text)const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks', {
method: 'GET',
headers: {
'Authorization': 'Bearer <token>'
}
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.dify.ai/v1/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))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyResponse
{
"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
}{
"code": "knowledge_fs_invalid_request",
"message": "Agent Knowledge Base request is invalid.",
"status": 400,
"violations": [
{
"field": [
"limit"
],
"type": "less_than_equal"
}
]
}{
"code": "knowledge_fs_invalid_credential",
"message": "Invalid Agent Knowledge Base service credential.",
"status": 401
}{
"code": "unauthorized",
"message": "Access token is invalid",
"status": 401
}{
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
"status": 403
}{
"code": "knowledge_fs_access_denied",
"message": "Agent Knowledge Base operation is not allowed.",
"status": 403
}{
"code": "knowledge_fs_resource_not_found",
"failure": {
"category": "not_found",
"code": "KNOWLEDGE_FS_NOT_FOUND",
"message": "The requested Agent Knowledge Base resource was not found.",
"retryPolicy": "never",
"traceId": "8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2"
},
"message": "The requested Agent Knowledge Base resource was not found.",
"status": 404
}{
"code": "not_found",
"message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
"status": 404
}{
"code": "knowledge_fs_upstream_unavailable",
"failure": {
"action": "contact_admin",
"category": "internal",
"code": "KNOWLEDGE_FS_INTERNAL_ERROR",
"message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
"retryPolicy": "manual",
"traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
},
"message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
"status": 502
}{
"code": "knowledge_fs_upstream_unavailable",
"message": "Agent Knowledge Base is unavailable.",
"status": 502
}{
"code": "knowledge_fs_operation_unavailable",
"message": "Agent Knowledge Base operation is not available.",
"status": 503
}{
"code": "knowledge_fs_operation_unavailable",
"failure": {
"action": "retry",
"category": "dependency",
"code": "KNOWLEDGE_FS_UNAVAILABLE",
"message": "A service required by Agent Knowledge Base is temporarily unavailable.",
"retryPolicy": "manual",
"traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
},
"message": "A service required by Agent Knowledge Base is temporarily unavailable.",
"status": 503
}get/knowledge-fs/spaces/{knowledge_base_id}/research-tasks
Authorization
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
Responses
application/json
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 attributesHide child attributes
Spend ceiling from the request in USD.
null when none was set.When the task reached
completed, failed, or canceled, in epoch milliseconds. null while the task is running.Spend recorded so far.
Show child attributesHide child attributes
true when spend crossed budgetUsd and the task was canceled for that reason. Absent otherwise.The request's
budgetUsd. Absent when no budget was set.One entry per recorded model call, oldest first.
Show child attributesHide child attributes
Cost of the call in USD.
Model provider that served the call.
Epoch milliseconds when the cost was recorded.
Step that made the call:
pageindex.layer, pageindex.semantic, pageindex.whole-tree, research.judge, research.plan, graph.plan, query.answer, or query.image-expand.Token usage of the call:
promptTokens, completionTokens, totalTokens, estimated, reserved, status (reserved, succeeded, or failed), and researchModelCallId. A reservation for a call still in flight is an entry too, and counts toward totalUsd.Sum of
entries[].costUsd in USD. 0 until the first model call is recorded.Epoch milliseconds when the task was created.
Failure code, the same value as failure.code. Present only when stage is failed, and null otherwise, including for canceled tasks.
On a failed research task, failure.code is one of RESEARCH_TASK_CAPABILITY_REVOKED, RESEARCH_TASK_DISPATCH_DEAD, RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED, RESEARCH_TASK_FAILED, RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID, or RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID.
Error details. Present only when stage is failed, and null otherwise. Members without a value are null here. traceId is the task ID.
When action is retry, create a new task with Create Research Task.
Show child attributesHide child attributes
Suggested next step, when there is one:
configure_model, configure_parser, configure_source, contact_admin, reupload, or retry. null when not applicable.Kind of failure:
authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.Research-task failure code, matching this task's
error.Public message for the task failure. Provider error details are not exposed.
Up to 8 values that qualify the failure, with keys among
attempt, currentRowVersion, documentCount, expectedRowVersion, fileSizeBytes, limit, maxFileSizeBytes, maxItems, modelType, providerKind, retryAfterSeconds, and status. null when there are none.Whether a retry can help:
automatic (the service retries on its own), manual (retry yourself), after_configuration (fix the knowledge base's setup in Dify first), or never (change the request).Always
research.Research task ID. Quote it when contacting an administrator.
Research task ID. Use it as
research_task_id in the task operations.Internal ID of the knowledge base. Not the knowledge base ID in the path.
Limits from the request, with snake_case keys.
null when the request carried no limits. A member that was not sent is null. Convert the keys back to camelCase before sending them to Create Research Task again.Show child attributesHide child attributes
The
metadata object sent at creation, without keys that start with __knowledgeFs.Retrieval depth of the task:
fast, deep, or research.The research question as stored.
Images used in the original query. Omitted for text-only queries.
Where the task is in its lifecycle. Tasks move forward one stage at a time:
queued: accepted, waiting for a worker.planning: resolving the retrieval plan.retrieving: searching the knowledge base. A retrieval checkpoint may be written.analyzing: reading and weighing the retrieved chunks.generating: writing the answer. The final result is written during this stage.completed: finished. Read its results with List Research Task Results.failed: stopped with an error. Seeerrorandfailure.canceled: stopped by Cancel Research Task or by the budget.paused: The task is paused. Check any failure details with the deployment operator, or cancel it.
completed, failed, and canceled are terminal.
Maximum number of chunks kept after the search results are merged and reranked: the request's
topK, or the knowledge base's TOP K when omitted.Epoch milliseconds of the last update to the task record, including internal checkpoints and retry scheduling.
Cursor for the next page, or
null on the last page. Send it back as cursor.