> ## 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. # List Document Indexing Tasks > Lists a document's indexing tasks from uploads and syncs, oldest first, each with its outcome. Failed and canceled tasks are included. The newest task is on the last page. For the task running now, read `latest_task` on [Get Document](/en/api-reference/documents-and-chunks/get-document) instead. An unknown document ID, including a document file ID, answers `200` with an empty `data`. A page can hold fewer than `limit` tasks, so follow `next_cursor` until it is `null`. For which task operation to use when, see [Track Indexing](/en/api-reference/guides/knowledge-base#track-indexing). ## OpenAPI ````yaml /en/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/logical-documents/{document_id}/processing-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}/logical-documents/{document_id}/processing-tasks: get: tags: - Indexing Tasks summary: List Document Indexing Tasks description: >- Lists a document's indexing tasks from uploads and syncs, oldest first, each with its outcome. Failed and canceled tasks are included. The newest task is on the last page. For the task running now, read `latest_task` on [Get Document](/en/api-reference/documents-and-chunks/get-document) instead. An unknown document ID, including a document file ID, answers `200` with an empty `data`. A page can hold fewer than `limit` tasks, so follow `next_cursor` until it is `null`. For which task operation to use when, see [Track Indexing](/en/api-reference/guides/knowledge-base#track-indexing). operationId: listDocumentIndexingTasks 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: >- The document ID, from [List Documents](/en/api-reference/documents-and-chunks/list-documents). in: path name: document_id required: true schema: format: uuid type: string - description: Cursor from the previous page's `next_cursor`. in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: Tasks per page. in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: Response Example value: data: - active_operations: - parse completed_at: '2026-09-03T10:03:40Z' created_at: '2026-09-03T10:02:11Z' document_id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e document_revision: 1 error_code: DOCUMENT_COMPILATION_FAILED error_message: >- The document could not be processed. Try again, or contact an administrator with the error reference. failure: action: contact_admin category: internal code: DOCUMENT_COMPILATION_FAILED message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. parameters: null retryPolicy: manual stage: parsing traceId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b phase: parsing progress_percent: 0 retry_at: null semantic_enrichment: error_code: null error_message: null failure: null nodes_completed: 0 nodes_total: null provider_calls: null provider_calls_maximum: null state: disabled updated_at: null stage: queued state: failed updated_at: '2026-09-03T10:03:40Z' - active_operations: [] completed_at: '2026-10-20T08:16:05Z' created_at: '2026-10-20T08:15:42Z' document_id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e document_revision: 2 error_code: null error_message: null failure: null id: c4e8a2f6-1b3d-4e5f-8a9b-0c1d2e3f4a5b knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b phase: complete progress_percent: 100 retry_at: null semantic_enrichment: error_code: null error_message: null failure: null nodes_completed: 18 nodes_total: 18 provider_calls: 12 provider_calls_maximum: 200 state: ready updated_at: '2026-10-20T08:17:30Z' stage: published state: succeeded updated_at: '2026-10-20T08:17:30Z' next_cursor: null schema: properties: data: description: One page of indexing tasks, oldest first. items: $ref: '#/components/schemas/KnowledgeBaseDocumentIndexingTask' type: array next_cursor: description: >- Cursor for the next page, or `null` on the last page. Send it back as `cursor`. nullable: true type: string type: object description: One page of indexing tasks. '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - limit type: greater_than_equal knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) 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: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 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`: `document_id` is not a UUID, or `cursor` is not a value from `next_cursor`. - `knowledge_fs_invalid_request`: `document_id` is malformed. '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_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied (rejected) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- You do not have permission to perform this Agent Knowledge Base operation. 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. - `knowledge_fs_access_denied`: the key has no access to this knowledge base's content. - `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: 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: >- - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '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_transport: summary: knowledge_fs_upstream_unavailable (no response) 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`. components: schemas: KnowledgeBaseDocumentIndexingTask: properties: active_operations: description: >- Operations under way in the current phase, such as `parse`, `chunk`, `embedding`, or `publication`. items: type: string nullable: true type: array completed_at: description: When the task ended, ISO 8601. `null` while it runs. nullable: true type: string created_at: description: >- When the task was created, ISO 8601. [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) reports the same task's times in epoch milliseconds. type: string document_id: description: Document ID. type: string document_revision: description: Revision this task builds. type: integer error_code: description: Error code when `state` is `failed`. nullable: true type: string error_message: description: The message for `error_code`. Can differ from `failure.message`. nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: >- Error details when `state` is `failed`. `stage` is the `phase` the task failed in, and `traceId` is the task ID. `null` otherwise. nullable: true id: description: >- Indexing task ID. The same ID works with [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task), [Cancel Indexing Task](/en/api-reference/indexing-tasks/cancel-indexing-task), and [Retry Indexing Task](/en/api-reference/indexing-tasks/retry-indexing-task). type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string phase: description: >- What the task is doing: `queued`, `parsing`, `outline_summary`, `chunking_indexing`, `graph_admission`, `publication`, or `complete`. nullable: true type: string progress_percent: description: Progress from 0 to 100, derived from `stage`. type: integer retry_at: description: >- When the automatic retry runs, ISO 8601. Set while `state` is `retry_wait`. nullable: true type: string semantic_enrichment: allOf: - $ref: '#/components/schemas/KnowledgeBaseSemanticEnrichment' description: >- Knowledge graph building status for the indexed content. Deep and Research searches follow the knowledge graph. When building wasn't scheduled, `state` is `not_scheduled` while the task runs and `disabled` once it has ended. nullable: true stage: description: >- Last checkpoint reached, in forward order: `queued`, `parsed`, `outline_built`, `nodes_generated`, `projection_built`, `smoke_eval_passed`, `published`. It stays at the last checkpoint when the task fails or is canceled, so read `state` for the outcome. type: string state: description: >- Run state: - `dispatch_pending`, `queued`: waiting for a worker. - `retry_wait`: an automatic retry is scheduled at `retry_at`. - `running`: a worker is indexing. - `succeeded`: the revision is published and serves queries. `semantic_enrichment` can still be running. - `failed`: see `failure`. Restart it with [Retry Indexing Task](/en/api-reference/indexing-tasks/retry-indexing-task). - `canceled`. - `superseded`: a newer attempt replaced this one. `succeeded`, `failed`, `canceled`, and `superseded` are terminal. type: string updated_at: description: When the task or its enrichment last changed, ISO 8601. type: string type: object KnowledgeBaseErrorDetails: 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; omitted from HTTP error bodies. 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: >- Stable error code in upper snake case, for example `KNOWLEDGE_FS_CONFLICT` or `SOURCE_CREDENTIAL_TEST_FAILED`. type: string message: description: >- Public message for the error code or failure category. 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; omitted from HTTP error bodies. 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: >- Stage the failure belongs to, for example `query_generation` or `credential-test`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string traceId: description: >- Reference to quote when contacting an administrator. May be `null` in a successful response containing failure details, or omitted from an HTTP error body. nullable: true type: string type: object KnowledgeBaseSemanticEnrichment: properties: error_code: description: Error code when `state` is `failed`. nullable: true type: string error_message: description: The message for `error_code`. Can differ from `failure.message`. nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: Error details when `state` is `failed`. `null` otherwise. nullable: true nodes_completed: description: >- Knowledge graph nodes built: `0` until `state` is `ready`, then the same as `nodes_total`. type: integer nodes_total: description: Knowledge graph nodes to build. `null` until known. nullable: true type: integer provider_calls: description: Model calls made so far. nullable: true type: integer provider_calls_maximum: description: Most model calls knowledge graph building may make. nullable: true type: integer state: description: >- `not_scheduled`, `pending`, `running`, `ready`, `failed`, or `disabled`. Knowledge graph building can still be `pending` or `running` after the indexing task has published its revision. type: string updated_at: description: When the enrichment last changed, ISO 8601. nullable: true type: string 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.