获取研究任务

get/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}

Request example

curl --request GET \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}"
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/{research_task_id}', {
  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/{research_task_id}',
  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/{research_task_id}"

	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/{research_task_id}"))
    .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/{research_task_id}')

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

{
  "budget_usd": 0.01,
  "completed_at": 1788681618000,
  "cost": {
    "budgetExceeded": true,
    "budgetUsd": 0.01,
    "entries": [
      {
        "costUsd": 0.0011,
        "provider": "openai",
        "recordedAt": 1788681603000,
        "step": "research.plan",
        "usage": {
          "completionTokens": 58,
          "estimated": false,
          "promptTokens": 310,
          "researchModelCallId": "attempt:1:call-4",
          "reserved": false,
          "status": "succeeded",
          "totalTokens": 368
        }
      },
      {
        "costUsd": 0.0096,
        "provider": "openai",
        "recordedAt": 1788681618000,
        "step": "research.judge",
        "usage": {
          "completionTokens": 190,
          "estimated": false,
          "promptTokens": 2640,
          "researchModelCallId": "attempt:1:call-5",
          "reserved": false,
          "status": "succeeded",
          "totalTokens": 2830
        }
      }
    ],
    "totalUsd": 0.0107
  },
  "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": "canceled",
  "top_k": 10,
  "updated_at": 1788681618000
}

{
  "budget_usd": 1.5,
  "completed_at": null,
  "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-6",
          "reserved": false,
          "status": "succeeded",
          "totalTokens": 368
        }
      }
    ],
    "totalUsd": 0.0011
  },
  "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": "retrieving",
  "top_k": 10,
  "updated_at": 1788681610000
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "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_access_denied",
  "failure": {
    "action": "contact_admin",
    "category": "authorization",
    "code": "KNOWLEDGE_FS_ACCESS_DENIED",
    "message": "You do not have permission to perform this Agent Knowledge Base operation.",
    "retryPolicy": "never",
    "traceId": "2a4d92fd-f0a6-4a39-abca-8944fc1b87b5"
  },
  "message": "You do not have permission to perform this Agent Knowledge Base operation.",
  "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": "e533c301-cd9c-48b7-a546-3bdce751dc31"
  },
  "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",
  "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/{research_task_id}

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/ 之后的那一段。

research_task_idstringrequired#

研究任务 ID，来自创建研究任务。

Responses

application/json

研究任务。

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 纪元毫秒），包括内部检查点和重试调度产生的更新。

规划研究任务取消研究任务