> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Plan Research Task > Estimates a research task without creating it. Returns the resolved retrieval depth and estimates of cost, latency, and work, including whether they fit the proposed budget. For the plan, create, poll, and read flow, see [Run a Research Task](/en/api-reference/guides/knowledge-base#run-a-research-task). ## OpenAPI ````yaml /en/api-reference/openapi_service.json post /knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan: post: tags: - Research Tasks summary: Plan Research Task description: >- Estimates a research task without creating it. Returns the resolved retrieval depth and estimates of cost, latency, and work, including whether they fit the proposed budget. For the plan, create, poll, and read flow, see [Run a Research Task](/en/api-reference/guides/knowledge-base#run-a-research-task). operationId: planResearchTask parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: Request Example value: budgetUsd: 0.05 mode: research query: >- What changed in the 2025 refund policy, and which regions are affected? topK: 10 schema: additionalProperties: false description: Provide a nonblank `query`. properties: budgetUsd: description: >- Spend ceiling in USD to compare with the cost estimate. Sets `budget.exceeds_budget` and `budget.remaining_budget_usd` in the response. minimum: 0 nullable: true type: number mode: description: >- Retrieval depth: `fast`, `deep`, or `research` (see [Retrieval Depth](/en/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth)). Omit it to use the knowledge base's default depth, `retrieval.default_mode` in [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings). enum: - fast - deep - research - null nullable: true type: string query: description: >- The question. Use a nonblank query. Also limited to 16,384 UTF-8 bytes. maxLength: 16000 nullable: false pattern: \S type: string topK: description: >- 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. maximum: 50 minimum: 1 nullable: true type: integer required: - query type: object description: >- Optional fields marked nullable treat `null` as omitted. The normalized request must fit within 65,536 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). required: true responses: '200': content: application/json: examples: success: summary: Response Example value: budget: budget_usd: 0.05 exceeds_budget: false remaining_budget_usd: 0.018238 estimates: cacheHitProbability: 0.25 costUsd: currency: USD estimated: 0.031762 max: 0.042879 min: 0.020645 inputTokens: 3070 latencyMs: p50: 2800 p95: 5040 outputTokens: 1776 retrievalSteps: 3 scannedResources: 620 toolCalls: 6 totalTokens: 4846 workBounds: modelCalls: estimated: 3 max: 4 min: 2 openedResources: estimated: 20 max: 40 min: 0 retrievalSteps: estimated: 3 max: 5 min: 1 knowledge_space_id: b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d query: >- What changed in the 2025 refund policy, and which regions are affected? retrieval_plan: dense_top_k: 100 fts_top_k: 100 fusion_limit: 50 query_language: latin requested_mode: research rerank_candidate_limit: 50 resolved_mode: research strategy_version: retrieval-planner-v2 top_k: 10 steps: - estimatedCostUsd: 0.003126 estimatedInputTokens: 274 estimatedLatencyMs: 350 estimatedOutputTokens: 192 estimatedToolCalls: 1 name: plan - estimatedCostUsd: 0.00124 estimatedInputTokens: 0 estimatedLatencyMs: 600 estimatedOutputTokens: 0 estimatedToolCalls: 3 name: retrieve - estimatedCostUsd: 0.007542 estimatedInputTokens: 978 estimatedLatencyMs: 650 estimatedOutputTokens: 384 estimatedToolCalls: 1 name: analyze - estimatedCostUsd: 0.019854 estimatedInputTokens: 1818 estimatedLatencyMs: 1200 estimatedOutputTokens: 1200 estimatedToolCalls: 1 name: generate strategy_version: research-dry-run-planner-v1 schema: properties: budget: description: >- Verdict of the cost estimate against the request's `budgetUsd`. properties: budget_usd: description: The request's `budgetUsd`. `null` when none was sent. nullable: true type: number exceeds_budget: description: >- `true` when `estimates.costUsd.estimated` is above `budgetUsd`. Always `false` without a budget. Advisory only: [Create Research Task](/en/api-reference/research-tasks/create-research-task) still accepts the task and cancels it when its next model call could pass the budget. type: boolean remaining_budget_usd: description: >- `budgetUsd` minus the estimated cost. Negative when over budget. `null` without a budget. nullable: true type: number type: object estimates: description: >- Work, cost, and latency estimates for the task. Compare them with the `limits` you intend to send to [Create Research Task](/en/api-reference/research-tasks/create-research-task). properties: cacheHitProbability: description: >- Estimated share of retrieval served from cache, from `0` to `1`. type: number costUsd: description: Estimated cost of the task. properties: currency: description: Always `USD`. type: string estimated: description: Point estimate in USD. type: number max: description: Upper bound in USD. type: number min: description: Lower bound in USD. type: number type: object inputTokens: description: Estimated model input tokens across all steps. type: integer latencyMs: description: >- Estimated end-to-end duration in milliseconds. Time the first poll of [Get Research Task](/en/api-reference/research-tasks/get-research-task) from `p50`. properties: p50: description: Median estimate. type: integer p95: description: >- 95th-percentile estimate. This is the value checked against `limits.timeoutMs`. type: integer type: object outputTokens: description: Estimated model output tokens across all steps. type: integer retrievalSteps: description: >- Estimated retrieval rounds. Checked against `limits.maxRetrievalSteps`. type: integer scannedResources: description: >- Estimated documents and sections read. Checked against `limits.maxScannedResources`. type: integer toolCalls: description: >- Estimated tool invocations. Checked against `limits.maxToolCalls`. type: integer totalTokens: description: '`inputTokens` plus `outputTokens`.' type: integer workBounds: description: >- Ranges behind the point estimates. [Create Research Task](/en/api-reference/research-tasks/create-research-task) checks the point estimates, not these ranges. properties: modelCalls: description: >- Estimated, minimum, and maximum number of model calls. properties: estimated: description: Point estimate. type: integer max: description: Upper bound. type: integer min: description: Lower bound. type: integer type: object openedResources: description: >- Estimated, minimum, and maximum number of documents and sections opened. properties: estimated: description: Point estimate. type: integer max: description: Upper bound. type: integer min: description: Lower bound. type: integer type: object retrievalSteps: description: >- Estimated, minimum, and maximum number of retrieval rounds. properties: estimated: description: Point estimate. type: integer max: description: Upper bound. type: integer min: description: Lower bound. type: integer type: object type: object type: object knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string query: description: The question with surrounding whitespace removed. type: string retrieval_plan: description: How the search would be run. properties: dense_top_k: description: Candidates taken from vector search. type: integer fts_top_k: description: Candidates taken from keyword search. type: integer fusion_limit: description: >- Candidates kept after merging vector and keyword results. type: integer query_language: description: >- Detected language of the question: `cjk`, `latin`, `mixed-cjk-latin`, or `other`. type: string requested_mode: description: >- The `mode` from the request, or the knowledge base's default depth when omitted: `fast`, `deep`, or `research`. type: string rerank_candidate_limit: description: Candidates passed to the rerank model. type: integer resolved_mode: description: >- The depth that would run: `fast`, `deep`, or `research`. Send the same `mode` to [Create Research Task](/en/api-reference/research-tasks/create-research-task). A different depth there checks your `limits` against different estimates. type: string strategy_version: description: >- Version of the retrieval strategy that built this plan. type: string top_k: description: >- Maximum number of chunks kept after the search results are merged and reranked. type: integer type: object steps: description: Per-step estimates, in execution order. items: properties: estimatedCostUsd: description: Estimated cost of the step in USD. type: number estimatedInputTokens: description: Estimated model input tokens. type: integer estimatedLatencyMs: description: Estimated duration in milliseconds. type: integer estimatedOutputTokens: description: Estimated model output tokens. type: integer estimatedToolCalls: description: Estimated tool invocations. type: integer name: description: >- Step name. `plan`, `retrieve`, `analyze`, and `generate` always appear, in that order. `inspect` follows `plan` when the retrieval strategy reads document outlines. type: string type: object type: array strategy_version: description: Version of the estimator. type: string type: object description: The plan and its estimates. '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request (validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - limits type: extra_forbidden knowledge_fs_invalid_request_2: summary: knowledge_fs_invalid_request (rejected upstream) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: d44c6dd1-da9c-46e7-81e1-5f09707c4352 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`: the request failed validation. `violations` names each failing field. - `knowledge_fs_invalid_request`: the body has an unknown field (including `knowledgeSpaceId`, `limits`, and `metadata`), a value outside its limits, or no nonblank `query`. - `knowledge_fs_invalid_request`: the knowledge base's retrieval settings cannot run the resolved depth, for example a score threshold with `rerank.enabled: false`. Check the rerank model configuration under **Settings** > **Retrieval** in Dify. The `failure` object carries `retryPolicy` `never`, not `after_configuration`. '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: 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: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: 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 description: >- - `knowledge_fs_resource_not_found`: the knowledge base ID isn't recognized. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`: the request, once Dify adds its defaults, exceeds 65,536 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_2: summary: knowledge_fs_upstream_unavailable (without error details) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. Retry after a pause. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: 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 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. - `knowledge_fs_operation_unavailable`: the knowledge base isn't ready for queries yet: no embedding model is active, or its settings haven't been published. Check `capabilities.query` in [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings) before retrying. - `knowledge_fs_operation_unavailable`: the knowledge base was upgraded from a classic knowledge base and is still disabling the documents that were disabled or archived there. Retry later. components: securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 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](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.