Cancel Research Task
Cancels a research task that has not finished and returns it with stage canceled.
The record is kept and results already written stay readable with List Research Task Results.
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
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).
Response
The task after cancellation. stage is canceled and completed_at is set. error stays 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.
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
Show child attributes
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
Show child attributes
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. Seeerrorandfailure.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.
Was this page helpful?
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
}