创建研究任务

post/knowledge-fs/spaces/{knowledge_base_id}/research-tasks

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <string>' \
  --header 'Content-Type: application/json' \
  --data '{
  "budgetUsd": 1.5,
  "limits": {
    "maxRetrievalSteps": 8,
    "maxScannedResources": 800,
    "maxToolCalls": 12,
    "timeoutMs": 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?",
  "topK": 10
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
headers = {
    "Authorization": "Bearer <token>",
    "Idempotency-Key": "<string>",
    "Content-Type": "application/json",
}
payload = {
    "budgetUsd": 1.5,
    "limits": {
        "maxRetrievalSteps": 8,
        "maxScannedResources": 800,
        "maxToolCalls": 12,
        "timeoutMs": 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?",
    "topK": 10
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Idempotency-Key': '<string>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "budgetUsd": 1.5,
    "limits": {
      "maxRetrievalSteps": 8,
      "maxScannedResources": 800,
      "maxToolCalls": 12,
      "timeoutMs": 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?",
    "topK": 10
  })
});

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 => 'POST',
  CURLOPT_POSTFIELDS => '{
  "budgetUsd": 1.5,
  "limits": {
    "maxRetrievalSteps": 8,
    "maxScannedResources": 800,
    "maxToolCalls": 12,
    "timeoutMs": 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?",
  "topK": 10
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Idempotency-Key: <string>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
	payload := strings.NewReader("{\n  \"budgetUsd\": 1.5,\n  \"limits\": {\n    \"maxRetrievalSteps\": 8,\n    \"maxScannedResources\": 800,\n    \"maxToolCalls\": 12,\n    \"timeoutMs\": 120000\n  },\n  \"metadata\": {\n    \"client_request_id\": \"client-20260907-0001\",\n    \"ticket\": \"SUP-1042\"\n  },\n  \"mode\": \"research\",\n  \"query\": \"What changed in the 2025 refund policy, and which regions are affected?\",\n  \"topK\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Idempotency-Key", "<string>")
	req.Header.Add("Content-Type", "application/json")

	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>")
    .header("Idempotency-Key", "<string>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"budgetUsd\": 1.5,\n  \"limits\": {\n    \"maxRetrievalSteps\": 8,\n    \"maxScannedResources\": 800,\n    \"maxToolCalls\": 12,\n    \"timeoutMs\": 120000\n  },\n  \"metadata\": {\n    \"client_request_id\": \"client-20260907-0001\",\n    \"ticket\": \"SUP-1042\"\n  },\n  \"mode\": \"research\",\n  \"query\": \"What changed in the 2025 refund policy, and which regions are affected?\",\n  \"topK\": 10\n}"))
    .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::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Idempotency-Key'] = '<string>'
request['Content-Type'] = 'application/json'
request.body = '{
  "budgetUsd": 1.5,
  "limits": {
    "maxRetrievalSteps": 8,
    "maxScannedResources": 800,
    "maxToolCalls": 12,
    "timeoutMs": 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?",
  "topK": 10
}'

response = http.request(request)
puts response.read_body

Response

{
  "budget_usd": 1.5,
  "completed_at": null,
  "cost": {
    "budgetUsd": 1.5,
    "entries": [],
    "totalUsd": 0
  },
  "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": "queued",
  "top_k": 10,
  "updated_at": 1788681600000
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "topK"
      ],
      "type": "less_than_equal"
    }
  ]
}

{
  "code": "knowledge_fs_invalid_request",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "30692184-e927-4398-b8f9-a6e1eda1ea7b"
  },
  "message": "The 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_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_conflict",
  "failure": {
    "action": "retry",
    "category": "conflict",
    "code": "KNOWLEDGE_FS_CONFLICT",
    "message": "The Agent Knowledge Base operation conflicts with the current resource state.",
    "retryPolicy": "manual",
    "traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
  },
  "message": "The Agent Knowledge Base operation conflicts with the current resource state.",
  "status": 409
}

{
  "code": "knowledge_fs_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

{
  "code": "knowledge_fs_request_rejected",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "9c729446-ba49-4733-9cc1-dbe73542d014"
  },
  "message": "The Agent Knowledge Base request is invalid.",
  "status": 422,
  "violations": [
    {
      "estimatedValue": 14,
      "limit": "maxToolCalls",
      "limitValue": 12
    }
  ]
}

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

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

Headers

Idempotency-Keystring#

可选的幂等键，用于安全地重试创建。使用 8～255 个可打印 ASCII 字符，首尾不得有空白；格式不正确的键返回 400。

用同一个 API 密钥重复发送相同的键和请求体，会以 202 返回原任务及其当前状态，不会再创建新任务。键在工作空间内唯一：以不同的请求体、通过其他 API 密钥、在其他知识库中或为其他操作复用该键，会返回 409。

Length: 8–255

Body

application/json

budgetUsdnumber#

花费上限（USD）。在任务运行期间生效，创建时不检查。即使规划研究任务的估算超出该上限，任务也会被受理。每次调用模型之前，任务会用这次调用的最坏情况成本对照预算检查；如果这次调用可能超出预算，任务会被取消，不再发起调用。

单次调用的实际成本仍可能高于其最坏情况估算，因此 cost.totalUsd 最终可能超过 budgetUsd。如果任务在 generating 阶段之前因预算被取消，就不会有回答。最坏情况成本通常远高于规划结果中的估算，因此需要得到回答时，把上限设得远高于 estimates.costUsd.max；topK 较大时还要更高。

因预算停止的任务，stage 为 canceled。

Range: >= 0

limitsobject#

仅在创建时对照规划结果中的估算检查一次。估算超出任一限制的任务会被拒绝并返回 422。省略 limits 则跳过这些检查。如需在任务运行期间限制花费，使用 budgetUsd。

估算值等于限制值时视为通过。参照规划研究任务返回的 estimates 设定这些值。

Show child attributes

maxRetrievalStepsinteger#

对照 estimates.retrievalSteps 检查。

Range: >= 1

maxScannedResourcesinteger#

对照 estimates.scannedResources 检查。

Range: >= 1

maxToolCallsinteger#

对照 estimates.toolCalls 检查。

Range: >= 1

timeoutMsinteger#

对照 estimates.latencyMs.p95 检查，单位为毫秒。

Range: >= 1

metadataobject#

自由格式的对象，随任务保存，并以 metadata 返回。以 __knowledgeFs 开头的键为保留键，会被丢弃。

可在其中放入 client_request_id 等唯一值，创建响应丢失时，可据此识别并找到该任务。如需让重试直接返回原任务、不再创建新任务，发送 Idempotency-Key。

modeenum<string>#

检索深度：fast、deep 或 research（参见检索深度）。省略时使用知识库的默认深度，即获取知识库设置中的 retrieval.default_mode。

Options:fastdeepresearchnull

querystringrequired#

要查询的问题。不能为空白，且不超过 16,384 个 UTF-8 字节。

Length: max 16000Pattern: \S

topKinteger#

检索结果合并并重排序后最多保留的分段数。显式传入的值必须在 1～50 之间。省略时使用知识库已发布的 Top K 设置，该设置最高可达 100。值越大，模型获得的上下文越多，干扰也越多；值越小，结果越集中，但可能漏掉相关分段。

Range: 1–50

Responses

application/json

任务已受理。stage 为 queued，mode 为实际采用的深度，cost.totalUsd 为 0。用相同的 Idempotency-Key 和请求体重复请求，会返回原任务及其当前状态。

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

获取研究任务列表规划研究任务