Cancel Research Task

DELETE

knowledge-fs

spaces

{knowledge_base_id}

research-tasks

{research_task_id}

Cancel Research Task

curl --request DELETE \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}"

	req, _ := http.NewRequest("DELETE", 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))

}

HttpResponse<String> response = Unirest.delete("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "budget_usd": 1.5,
  "completed_at": 1788681605000,
  "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": "canceled",
  "top_k": 10,
  "updated_at": 1788681605000
}

Authorizations

Authorization

string

header

required

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_id

string<uuid>

required

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_id

string<uuid>

required

Research task ID. From Create Research Task.

Response

The task after cancellation. stage is canceled and completed_at is set. error stays null.

budget_usd

number | null

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

completed_at

number | null

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

cost

object

Spend recorded so far.

Show child attributes

created_at

number

Epoch milliseconds when the task was created.

error

string | null

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.

failure

object | null

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

string

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

knowledge_space_id

string

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

limits

object | null

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

metadata

object

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

mode

string | null

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

query

string

The research question as stored.

query_images

object[]

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

Show child attributes

stage

string

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_k

integer | null

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_at

number

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

Cancel Research Task

curl --request DELETE \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}"

	req, _ := http.NewRequest("DELETE", 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))

}

HttpResponse<String> response = Unirest.delete("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks/{research_task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "budget_usd": 1.5,
  "completed_at": 1788681605000,
  "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": "canceled",
  "top_k": 10,
  "updated_at": 1788681605000
}

Guides

App APIs

Knowledge APIs

Cancel Research Task

Authorizations

Path Parameters

Response