> ## 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. # 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](/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 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: post: tags: - Research Tasks summary: Create Research Task description: >- 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](/en/api-reference/guides/knowledge-base#run-a-research-task). operationId: createResearchTask 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 - description: >- 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`. in: header name: Idempotency-Key required: false schema: maxLength: 255 minLength: 8 type: string requestBody: content: application/json: examples: request: summary: Request Example value: 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 schema: additionalProperties: false description: Provide a nonblank `query`. properties: budgetUsd: description: >- Spend ceiling in USD. Enforced while the task runs, not at creation. The task is accepted even when the [Plan Research Task](/en/api-reference/research-tasks/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`. minimum: 0 nullable: true type: number limits: additionalProperties: false description: >- Checked 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](/en/api-reference/research-tasks/plan-research-task). nullable: true properties: maxRetrievalSteps: description: Checked against `estimates.retrievalSteps`. minimum: 1 nullable: true type: integer maxScannedResources: description: Checked against `estimates.scannedResources`. minimum: 1 nullable: true type: integer maxToolCalls: description: Checked against `estimates.toolCalls`. minimum: 1 nullable: true type: integer timeoutMs: description: >- Checked against `estimates.latencyMs.p95`, in milliseconds. minimum: 1 nullable: true type: integer type: object metadata: description: >- 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`. type: object 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: '202': content: application/json: examples: success: summary: Response Example value: 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 schema: $ref: '#/components/schemas/KnowledgeBaseResearchTask' description: >- 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. '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: - topK type: less_than_equal 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: 30692184-e927-4398-b8f9-a6e1eda1ea7b 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`), 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`. - `knowledge_fs_invalid_request`: `Idempotency-Key` is not 8 to 255 printable ASCII characters, or has leading or trailing whitespace. '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. '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`: `Idempotency-Key` was already used with a different body, from another API key, in another knowledge base, or for another operation. Use a new key for a new task. '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). '422': content: application/json: examples: knowledge_fs_request_rejected: summary: knowledge_fs_request_rejected value: code: knowledge_fs_request_rejected failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 9c729446-ba49-4733-9cc1-dbe73542d014 message: The Agent Knowledge Base request is invalid. status: 422 violations: - estimatedValue: 14 limit: maxToolCalls limitValue: 12 description: >- - `knowledge_fs_request_rejected`: the plan's estimates exceed one or more of your `limits`. Each `violations` entry names one: `limit` (the limit's request name), `estimatedValue`, and `limitValue`. An estimate equal to its limit passes. When a 422 persists against `limits` you sized from a plan, omit `limits` and bound the task with `budgetUsd` instead. '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. The task may already have started. If you sent `Idempotency-Key`, send the same request again with the same key: it returns the original task instead of creating another. Without a key, use the same API key to [List Research Tasks](/en/api-reference/research-tasks/list-research-tasks) before creating another. Follow every page and inspect each task's `metadata` for the unique value you sent. Keep a matching task's ID and poll it. '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: schemas: KnowledgeBaseResearchTask: properties: budget_usd: description: Spend ceiling from the request in USD. `null` when none was set. nullable: true type: number completed_at: description: >- When the task reached `completed`, `failed`, or `canceled`, in epoch milliseconds. `null` while the task is running. nullable: true type: number cost: description: Spend recorded so far. properties: budgetExceeded: description: >- `true` when spend crossed `budgetUsd` and the task was canceled for that reason. Absent otherwise. type: boolean budgetUsd: description: The request's `budgetUsd`. Absent when no budget was set. type: number entries: description: One entry per recorded model call, oldest first. items: properties: costUsd: description: Cost of the call in USD. type: number provider: description: Model provider that served the call. type: string recordedAt: description: Epoch milliseconds when the cost was recorded. type: number step: description: >- Step that made the call: `pageindex.layer`, `pageindex.semantic`, `pageindex.whole-tree`, `research.judge`, `research.plan`, `graph.plan`, `query.answer`, or `query.image-expand`. type: string usage: description: >- Token usage of the call: `promptTokens`, `completionTokens`, `totalTokens`, `estimated`, `reserved`, `status` (`reserved`, `succeeded`, or `failed`), and `researchModelCallId`. A reservation for a call still in flight is an entry too, and counts toward `totalUsd`. type: object type: object type: array totalUsd: description: >- Sum of `entries[].costUsd` in USD. `0` until the first model call is recorded. type: number type: object created_at: description: Epoch milliseconds when the task was created. type: number error: description: >- 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`. nullable: true type: string failure: description: >- 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](/en/api-reference/research-tasks/create-research-task). nullable: true properties: action: description: >- Suggested next step, when there is one: `configure_model`, `configure_parser`, `configure_source`, `contact_admin`, `reupload`, or `retry`. `null` when not applicable. nullable: true type: string category: description: >- Kind of failure: `authorization`, `canceled`, `configuration`, `conflict`, `dependency`, `internal`, `not_found`, `rate_limit`, `timeout`, or `validation`. type: string code: description: Research-task failure code, matching this task's `error`. type: string message: description: >- Public message for the task failure. Provider error details are not exposed. type: string parameters: additionalProperties: true description: >- Up to 8 values that qualify the failure, with keys among `attempt`, `currentRowVersion`, `documentCount`, `expectedRowVersion`, `fileSizeBytes`, `limit`, `maxFileSizeBytes`, `maxItems`, `modelType`, `providerKind`, `retryAfterSeconds`, and `status`. `null` when there are none. nullable: true type: object retryPolicy: description: >- Whether a retry can help: `automatic` (the service retries on its own), `manual` (retry yourself), `after_configuration` (fix the knowledge base's setup in Dify first), or `never` (change the request). type: string stage: description: Always `research`. nullable: true type: string traceId: description: Research task ID. Quote it when contacting an administrator. nullable: true type: string type: object id: description: >- Research task ID. Use it as `research_task_id` in the task operations. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string limits: description: >- 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](/en/api-reference/research-tasks/create-research-task) again. nullable: true properties: max_retrieval_steps: description: Value of the request's `limits.maxRetrievalSteps`. nullable: true type: integer max_scanned_resources: description: Value of the request's `limits.maxScannedResources`. nullable: true type: integer max_tool_calls: description: Value of the request's `limits.maxToolCalls`. nullable: true type: integer timeout_ms: description: Value of the request's `limits.timeoutMs`. nullable: true type: integer type: object metadata: description: >- The `metadata` object sent at creation, without keys that start with `__knowledgeFs`. type: object mode: description: 'Retrieval depth of the task: `fast`, `deep`, or `research`.' nullable: true type: string query: description: The research question as stored. type: string query_images: description: Images used in the original query. Omitted for text-only queries. items: properties: byte_size: description: Always `null` in this API. minimum: 0 nullable: true type: integer mime_type: description: Always `null` in this API. nullable: true type: string name: description: Always `null` in this API. nullable: true type: string preview_url: description: Always `null` in this API. nullable: true type: string upload_file_id: description: ID of the image file used in the original query. type: string required: - upload_file_id type: object type: array stage: description: >- 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](/en/api-reference/research-tasks/list-research-task-results). - `failed`: stopped with an error. See `error` and `failure`. - `canceled`: stopped by [Cancel Research Task](/en/api-reference/research-tasks/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. type: string top_k: description: >- 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. nullable: true type: integer updated_at: description: >- Epoch milliseconds of the last update to the task record, including internal checkpoints and retry scheduling. type: number type: object 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.