Plan Research Task

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

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "budgetUsd": 0.05,
  "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/plan"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "budgetUsd": 0.05,
    "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/plan', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "budgetUsd": 0.05,
    "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/plan',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "budgetUsd": 0.05,
  "mode": "research",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "topK": 10
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    '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/plan"
	payload := strings.NewReader("{\n  \"budgetUsd\": 0.05,\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("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/plan"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"budgetUsd\": 0.05,\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/plan')

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['Content-Type'] = 'application/json'
request.body = '{
  "budgetUsd": 0.05,
  "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": {
    "budget_usd": 0.05,
    "exceeds_budget": false,
    "remaining_budget_usd": 0.018238
  },
  "estimates": {
    "cacheHitProbability": 0.25,
    "costUsd": {
      "currency": "USD",
      "estimated": 0.031762,
      "max": 0.042879,
      "min": 0.020645
    },
    "inputTokens": 3070,
    "latencyMs": {
      "p50": 2800,
      "p95": 5040
    },
    "outputTokens": 1776,
    "retrievalSteps": 3,
    "scannedResources": 620,
    "toolCalls": 6,
    "totalTokens": 4846,
    "workBounds": {
      "modelCalls": {
        "estimated": 3,
        "max": 4,
        "min": 2
      },
      "openedResources": {
        "estimated": 20,
        "max": 40,
        "min": 0
      },
      "retrievalSteps": {
        "estimated": 3,
        "max": 5,
        "min": 1
      }
    }
  },
  "knowledge_space_id": "b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d",
  "query": "What changed in the 2025 refund policy, and which regions are affected?",
  "retrieval_plan": {
    "dense_top_k": 100,
    "fts_top_k": 100,
    "fusion_limit": 50,
    "query_language": "latin",
    "requested_mode": "research",
    "rerank_candidate_limit": 50,
    "resolved_mode": "research",
    "strategy_version": "retrieval-planner-v2",
    "top_k": 10
  },
  "steps": [
    {
      "estimatedCostUsd": 0.003126,
      "estimatedInputTokens": 274,
      "estimatedLatencyMs": 350,
      "estimatedOutputTokens": 192,
      "estimatedToolCalls": 1,
      "name": "plan"
    },
    {
      "estimatedCostUsd": 0.00124,
      "estimatedInputTokens": 0,
      "estimatedLatencyMs": 600,
      "estimatedOutputTokens": 0,
      "estimatedToolCalls": 3,
      "name": "retrieve"
    },
    {
      "estimatedCostUsd": 0.007542,
      "estimatedInputTokens": 978,
      "estimatedLatencyMs": 650,
      "estimatedOutputTokens": 384,
      "estimatedToolCalls": 1,
      "name": "analyze"
    },
    {
      "estimatedCostUsd": 0.019854,
      "estimatedInputTokens": 1818,
      "estimatedLatencyMs": 1200,
      "estimatedOutputTokens": 1200,
      "estimatedToolCalls": 1,
      "name": "generate"
    }
  ],
  "strategy_version": "research-dry-run-planner-v1"
}

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

{
  "code": "knowledge_fs_invalid_request",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "d44c6dd1-da9c-46e7-81e1-5f09707c4352"
  },
  "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_request_too_large",
  "message": "Agent Knowledge Base request is too large.",
  "status": 413
}

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

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.

Body

application/json

budgetUsdnumber#

Spend ceiling in USD to compare with the cost estimate. Sets budget.exceeds_budget and budget.remaining_budget_usd in the response.

Range: >= 0

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 plan and its estimates.

budgetobject#

Verdict of the cost estimate against the request's budgetUsd.

Show child attributes

budget_usdnumber#

The request's budgetUsd. null when none was sent.

exceeds_budgetboolean#

true when estimates.costUsd.estimated is above budgetUsd. Always false without a budget. Advisory only: Create Research Task still accepts the task and cancels it when its next model call could pass the budget.

remaining_budget_usdnumber#

budgetUsd minus the estimated cost. Negative when over budget. null without a budget.

estimatesobject#

Work, cost, and latency estimates for the task. Compare them with the limits you intend to send to Create Research Task.

Show child attributes

cacheHitProbabilitynumber#

Estimated share of retrieval served from cache, from 0 to 1.

costUsdobject#

Estimated cost of the task.

Show child attributes

currencystring#

Always USD.

estimatednumber#

Point estimate in USD.

maxnumber#

Upper bound in USD.

minnumber#

Lower bound in USD.

inputTokensinteger#

Estimated model input tokens across all steps.

latencyMsobject#

Estimated end-to-end duration in milliseconds. Time the first poll of Get Research Task from p50.

Show child attributes

p50integer#

Median estimate.

p95integer#

95th-percentile estimate. This is the value checked against limits.timeoutMs.

outputTokensinteger#

Estimated model output tokens across all steps.

retrievalStepsinteger#

Estimated retrieval rounds. Checked against limits.maxRetrievalSteps.

scannedResourcesinteger#

Estimated documents and sections read. Checked against limits.maxScannedResources.

toolCallsinteger#

Estimated tool invocations. Checked against limits.maxToolCalls.

totalTokensinteger#

inputTokens plus outputTokens.

workBoundsobject#

Ranges behind the point estimates. Create Research Task checks the point estimates, not these ranges.

Show child attributes

modelCallsobject#

Estimated, minimum, and maximum number of model calls.

Show child attributes

estimatedinteger#

Point estimate.

maxinteger#

Upper bound.

mininteger#

Lower bound.

openedResourcesobject#

Estimated, minimum, and maximum number of documents and sections opened.

Show child attributes

estimatedinteger#

Point estimate.

maxinteger#

Upper bound.

mininteger#

Lower bound.

retrievalStepsobject#

Estimated, minimum, and maximum number of retrieval rounds.

Show child attributes

estimatedinteger#

Point estimate.

maxinteger#

Upper bound.

mininteger#

Lower bound.

knowledge_space_idstring#

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

querystring#

The question with surrounding whitespace removed.

retrieval_planobject#

How the search would be run.

Show child attributes

dense_top_kinteger#

Candidates taken from vector search.

fts_top_kinteger#

Candidates taken from keyword search.

fusion_limitinteger#

Candidates kept after merging vector and keyword results.

query_languagestring#

Detected language of the question: cjk, latin, mixed-cjk-latin, or other.

requested_modestring#

The mode from the request, or the knowledge base's default depth when omitted: fast, deep, or research.

rerank_candidate_limitinteger#

Candidates passed to the rerank model.

resolved_modestring#

The depth that would run: fast, deep, or research. Send the same mode to Create Research Task. A different depth there checks your limits against different estimates.

strategy_versionstring#

Version of the retrieval strategy that built this plan.

top_kinteger#

Maximum number of chunks kept after the search results are merged and reranked.

stepsobject[]#

Per-step estimates, in execution order.

Show child attributes

estimatedCostUsdnumber#

Estimated cost of the step in USD.

estimatedInputTokensinteger#

Estimated model input tokens.

estimatedLatencyMsinteger#

Estimated duration in milliseconds.

estimatedOutputTokensinteger#

Estimated model output tokens.

estimatedToolCallsinteger#

Estimated tool invocations.

namestring#

Step name. plan, retrieve, analyze, and generate always appear, in that order. inspect follows plan when the retrieval strategy reads document outlines.

strategy_versionstring#

Version of the estimator.

Create Research Task Get Research Task