Create Research Task
Creates a research task for a question and returns it with stage queued. The task then runs in the background. For the plan, create, poll, and read flow, see Run a Research Task.
curl --request POST \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks \
--header 'Authorization: Bearer <token>' \
--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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
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
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', '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
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/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("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\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}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\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}"
response = http.request(request)
puts response.read_body{
"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
}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).
Headers
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.
8 - 255Path Parameters
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
Optional fields marked nullable treat null as omitted.
The normalized request must fit within 65,536 UTF-8 bytes. See Request Size Limits.
Provide a nonblank query.
The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes.
16000\SSpend 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.
x >= 0Checked 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
Show child attributes
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.
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.
fast, deep, research, null 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.
1 <= x <= 50Response
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.
Spend ceiling from the request in USD. null when none was set.
When the task reached completed, failed, or canceled, in epoch milliseconds. null while the task is running.
Spend recorded so far.
Show child attributes
Show child attributes
Epoch milliseconds when the task was created.
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
Research task ID. Use it as research_task_id in the task operations.
Internal ID of the knowledge base. Not the knowledge base ID in the path.
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
The metadata object sent at creation, without keys that start with __knowledgeFs.
Retrieval depth of the task: fast, deep, or research.
The research question as stored.
Images used in the original query. Omitted for text-only queries.
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.
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.
Epoch milliseconds of the last update to the task record, including internal checkpoints and retry scheduling.
Was this page helpful?
curl --request POST \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks \
--header 'Authorization: Bearer <token>' \
--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_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks"
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
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', '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
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/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("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\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}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/research-tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\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}"
response = http.request(request)
puts response.read_body{
"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
}