获取研究任务列表

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_body

Response

{
  "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

Authorizationstringheaderrequired#

每个请求都通过 API Key 认证：Authorization: Bearer {API_KEY}。应用接口使用应用 API Key，知识库接口使用知识库 API Key（快速开始）。

API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP 401（unauthorized）。

Path parameters

knowledge_base_idstringrequired#

知识库 ID：即知识库 API 访问 对话框中所示服务 API 端点的最后一段（…/knowledge-fs/spaces/<knowledge base ID>），也是地址栏中 /datasets/new/ 之后的那一段。

Query parameters

cursorstring#

游标，取自上一页的 next_cursor。

Length: 1–1000

limitinteger#

每页任务数。

Default: 50

Range: 1–100

Responses

application/json

一页研究任务。

dataobject[]#

研究任务，最新的在前。每一项都与获取研究任务返回的对象相同，不包含回答。

Show child attributes

budget_usdnumber#

请求中设置的花费上限，单位为 USD。未设置时为 null。

completed_atnumber#

任务到达 completed、failed 或 canceled 的时间，Unix 纪元毫秒。任务运行期间为 null。

costobject#

目前已记录的花费。

Show child attributes

budgetExceededboolean#

花费超出 budgetUsd 并因此取消任务时为 true，否则不返回此字段。

budgetUsdnumber#

请求中的 budgetUsd。未设置预算时不返回此字段。

entriesobject[]#

每次已记录的模型调用对应一项，最早的在前。

Show child attributes

costUsdnumber#

该次调用的花费，单位为 USD。

providerstring#

处理该次调用的模型供应商。

recordedAtnumber#

记录该花费的时间，Unix 纪元毫秒。

stepstring#

发起该调用的步骤：pageindex.layer、pageindex.semantic、pageindex.whole-tree、research.judge、research.plan、graph.plan、query.answer 或 query.image-expand。

usageobject#

该次调用的 token 用量：promptTokens、completionTokens、totalTokens、estimated、reserved、status（reserved、succeeded 或 failed）和 researchModelCallId。仍在进行中的调用所预留的额度也算作一项，并计入 totalUsd。

totalUsdnumber#

entries[].costUsd 的总和，单位为 USD。记录第一次模型调用之前为 0。

created_atnumber#

任务创建时间，Unix 纪元毫秒。

errorstring#

错误码，与 failure.code 的值相同。仅当 stage 为 failed 时有值，其他情况下为 null，已取消的任务也是如此。

研究任务失败时，failure.code 为以下之一：RESEARCH_TASK_CAPABILITY_REVOKED、RESEARCH_TASK_DISPATCH_DEAD、RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED、RESEARCH_TASK_FAILED、RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID 或 RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID。

failureobject#

错误详情。仅当 stage 为 failed 时有值，其他情况下为 null。此处没有值的成员为 null。traceId 为任务 ID。

当 action 为 retry 时，使用创建研究任务创建新任务。

Show child attributes

actionstring#

建议的下一步操作（如有）：configure_model、configure_parser、configure_source、contact_admin、reupload 或 retry。不适用时为 null。

categorystring#

失败类别：authorization、canceled、configuration、conflict、dependency、internal、not_found、rate_limit、timeout 或 validation。

codestring#

研究任务的错误码，与此任务的 error 一致。

messagestring#

任务失败的公开消息。不会暴露提供商的错误详情。

parametersobject#

描述失败细节的值，最多 8 个，键取自 attempt、currentRowVersion、documentCount、expectedRowVersion、fileSizeBytes、limit、maxFileSizeBytes、maxItems、modelType、providerKind、retryAfterSeconds 和 status。没有时为 null。

retryPolicystring#

重试是否有用：automatic（服务会自动重试）、manual（需自行重试）、after_configuration（先在 Dify 中修正知识库配置）或 never（需修改请求）。

stagestring#

始终为 research。

traceIdstring#

研究任务 ID。联系管理员时提供此 ID。

idstring#

研究任务 ID。在研究任务的各项操作中用作 research_task_id。

knowledge_space_idstring#

知识库的内部 ID，并非路径中的知识库 ID。

limitsobject#

请求中的限制项，键名为 snake_case。请求未携带 limits 时为 null，未发送的成员为 null。再次发送给创建研究任务前，需将键名转换回 camelCase。

Show child attributes

max_retrieval_stepsinteger#

请求中 limits.maxRetrievalSteps 的值。

max_scanned_resourcesinteger#

请求中 limits.maxScannedResources 的值。

max_tool_callsinteger#

请求中 limits.maxToolCalls 的值。

timeout_msinteger#

请求中 limits.timeoutMs 的值。

metadataobject#

创建时发送的 metadata 对象，不含以 __knowledgeFs 开头的键。

modestring#

任务的检索深度：fast、deep 或 research。

querystring#

存储的研究问题。

query_imagesobject[]#

原始查询中使用的图片。纯文本查询不返回此字段。

Show child attributes

byte_sizeinteger#

在此 API 中始终为 null。

Range: >= 0

mime_typestring#

在此 API 中始终为 null。

namestring#

在此 API 中始终为 null。

preview_urlstring#

在此 API 中始终为 null。

upload_file_idstringrequired#

原始查询中所用图片文件的 ID。

stagestring#

任务在生命周期中所处的阶段。任务每次前进一个阶段：

queued：已受理，等待工作进程处理。
planning：正在确定检索计划。
retrieving：正在检索知识库，可能会写入检索检查点。
analyzing：正在阅读和权衡检索到的分段。
generating：正在撰写回答，最终结果在此阶段写入。
completed：已完成。可用获取研究任务结果列表读取结果。
failed：因错误停止。详见 error 和 failure。
canceled：因取消研究任务或超出预算而停止。
paused：任务已暂停。可向部署的运维人员确认失败详情（如有），或取消该任务。

completed、failed 和 canceled 为终态。

top_kinteger#

检索结果合并并重排序后最多保留的分段数：取请求中的 topK，未传时取知识库的 Top K。

updated_atnumber#

任务记录最后更新的时间（Unix 纪元毫秒），包括内部检查点和重试调度产生的更新。

next_cursorstring#

下一页的游标，最后一页时为 null。将其作为 cursor 传回。

获取缺失分段列表创建研究任务