Skip to main content
POST
Plan Research Task

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.

Body

application/json

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.

query
string
required

The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes.

Maximum string length: 16000
Pattern: \S
budgetUsd
number | null

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

Required range: x >= 0
mode
enum<string> | null

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.

Available options:
fast,
deep,
research,
null
topK
integer | 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.

Required range: 1 <= x <= 50

Response

The plan and its estimates.

budget
object

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

estimates
object

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

knowledge_space_id
string

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

query
string

The question with surrounding whitespace removed.

retrieval_plan
object

How the search would be run.

steps
object[]

Per-step estimates, in execution order.

strategy_version
string

Version of the estimator.