Create Research Task

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#

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_idstringrequired#

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.

Headers

Idempotency-Keystring#

Optional key that makes creation safe to retry. Use 8 to 255 printable ASCII characters without leading or trailing whitespace; a malformed key answers 400.

Repeating the same key and body with the same API key returns the original task, in its current state, with 202 instead of creating another. Keys are unique within the workspace: reusing a key with a different body, from another API key, in another knowledge base, or for another operation answers 409.

Length: 8–255

Body

application/json

budgetUsdnumber#

Spend ceiling in USD. Enforced while the task runs, not at creation. The task is accepted even when the Plan Research Task estimate exceeds it. Before each model call, the task checks the call's worst-case cost against the budget, and it is canceled instead of making a call that could pass the budget.

A call can still cost more than its worst-case estimate, so cost.totalUsd can end above budgetUsd. A budget cancellation before the generating stage leaves the task with no answer. Worst-case costs usually run well above the plan's estimates, so when you need an answer, set the ceiling well above estimates.costUsd.max, and higher still for a large topK.

A task stopped by its budget ends in stage canceled.

Range: >= 0

limitsobject#

Checked once, at creation, against the plan's estimates. A task whose estimates exceed a limit is rejected with 422. Omitting limits skips these checks. Use budgetUsd to bound spending while the task runs.

An estimate equal to its limit passes. Size these against the estimates from Plan Research Task.

Show child attributes

maxRetrievalStepsinteger#

Checked against estimates.retrievalSteps.

Range: >= 1

maxScannedResourcesinteger#

Checked against estimates.scannedResources.

Range: >= 1

maxToolCallsinteger#

Checked against estimates.toolCalls.

Range: >= 1

timeoutMsinteger#

Checked against estimates.latencyMs.p95, in milliseconds.

Range: >= 1

metadataobject#

Free-form object stored with the task and returned as metadata. Keys that start with __knowledgeFs are reserved and dropped.

Include a unique value such as client_request_id to recognize the task if the creation response is lost. This helps you find the task. To make a retry return the original task instead of creating another, send Idempotency-Key.

modeenum<string>#

Retrieval depth: fast, deep, or research (see Retrieval Depth). Omit it to use the knowledge base's default depth, retrieval.default_mode in Get Knowledge Base Settings.

Options:fastdeepresearchnull

querystringrequired#

The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes.

Length: max 16000Pattern: \S

topKinteger#

Maximum number of chunks kept after the search results are merged and reranked. Explicit values must be between 1 and 50. If omitted, uses the knowledge base's published TOP K setting, which can be up to 100. Higher values give the model more context and more noise. Lower values stay focused and can miss relevant chunks.

Range: 1–50

Responses

application/json

The task was accepted. stage is queued, mode is the resolved depth, and cost.totalUsd is 0. A repeat with the same Idempotency-Key and body returns the original task in its current state.

budget_usdnumber#

Spend ceiling from the request in USD. null when none was set.

completed_atnumber#

When the task reached completed, failed, or canceled, in epoch milliseconds. null while the task is running.

costobject#

Spend recorded so far.

Show child attributes

budgetExceededboolean#

true when spend crossed budgetUsd and the task was canceled for that reason. Absent otherwise.

budgetUsdnumber#

The request's budgetUsd. Absent when no budget was set.

entriesobject[]#

One entry per recorded model call, oldest first.

Show child attributes

costUsdnumber#

Cost of the call in USD.

providerstring#

Model provider that served the call.

recordedAtnumber#

Epoch milliseconds when the cost was recorded.

stepstring#

Step that made the call: pageindex.layer, pageindex.semantic, pageindex.whole-tree, research.judge, research.plan, graph.plan, query.answer, or query.image-expand.

usageobject#

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.

totalUsdnumber#

Sum of entries[].costUsd in USD. 0 until the first model call is recorded.

created_atnumber#

Epoch milliseconds when the task was created.

errorstring#

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.

failureobject#

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 attributes

actionstring#

Suggested next step, when there is one: configure_model, configure_parser, configure_source, contact_admin, reupload, or retry. null when not applicable.

categorystring#

Kind of failure: authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.

codestring#

Research-task failure code, matching this task's error.

messagestring#

Public message for the task failure. Provider error details are not exposed.

parametersobject#

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.

retryPolicystring#

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).

stagestring#

Always research.

traceIdstring#

Research task ID. Quote it when contacting an administrator.

idstring#

Research task ID. Use it as research_task_id in the task operations.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

limitsobject#

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 attributes

max_retrieval_stepsinteger#

Value of the request's limits.maxRetrievalSteps.

max_scanned_resourcesinteger#

Value of the request's limits.maxScannedResources.

max_tool_callsinteger#

Value of the request's limits.maxToolCalls.

timeout_msinteger#

Value of the request's limits.timeoutMs.

metadataobject#

The metadata object sent at creation, without keys that start with __knowledgeFs.

modestring#

Retrieval depth of the task: fast, deep, or research.

querystring#

The research question as stored.

query_imagesobject[]#

Images used in the original query. Omitted for text-only queries.

Show child attributes

byte_sizeinteger#

Always null in this API.

Range: >= 0

mime_typestring#

Always null in this API.

namestring#

Always null in this API.

preview_urlstring#

Always null in this API.

upload_file_idstringrequired#

ID of the image file used in the original query.

stagestring#

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. See error and failure.
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.

top_kinteger#

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.

updated_atnumber#

Epoch milliseconds of the last update to the task record, including internal checkpoints and retry scheduling.

List Research Tasks Plan Research Task