Get Research Task - Dify Docs

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#

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.

research_task_idstringrequired#

Research task ID. From Create Research Task.

Responses

application/json

The research task.

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.

Plan Research Task Cancel Research Task