> ## 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. # 获取索引任务 > 返回一个索引任务的状态。索引任务负责把文档文件的某个版本变成生效的修订版本。 轮询直到 `stage` 为 `published`、`failed` 或 `canceled`。`stage` 未变化时，可通过 `run_state` 判断任务是在等待（`queued`、`dispatch_pending`、`retry_wait`）还是正在运行（`running`）。重新索引流程详见 [重新索引并跟踪索引进度](/zh/api-reference/guides/knowledge-base#track-indexing)。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id} openapi: 3.0.1 info: description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。 title: Dify 服务 API version: 1.0.0 servers: - description: Dify 服务 API 的基础 URL。自部署时，替换为你的 API 基础 URL。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API 基础 URL 的主机与路径，不含 `https://` 前缀。 security: - ApiKeyAuth: [] tags: - description: 与聊天消息和交互相关的操作。 name: 对话消息 - description: 文件上传和预览操作。 name: 文件操作 - description: 终端用户信息相关操作。 name: 终端用户 - description: 用户反馈操作。 name: 消息反馈 - description: 与管理会话相关的操作。 name: 会话管理 - description: 文字转语音和语音转文字操作。 name: 语音与文字转换 - description: 获取应用设置和信息的操作。 name: 应用配置 - description: 与管理标注直接回复相关的操作。 name: 标注管理 - description: 暂停等待人工输入的工作流恢复操作。 name: 人工介入 - description: 用于执行和管理工作流的操作。 name: 工作流运行 - description: 文本生成相关操作。 name: 文本生成消息 - description: 用于管理知识库的操作，包括创建、配置和检索。 name: 知识库 - description: 用于在知识库中创建、更新和管理文档的操作。 name: 文档 - description: 用于管理分段和子分段的操作。 name: 分段 - description: 用于管理知识库元数据字段和文档元数据值的操作。 name: 元数据 - description: 用于管理知识库标签和标签绑定的操作。 name: 标签 - description: 用于获取可用模型的操作。 name: 模型 - description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 name: 知识流水线 - description: 向知识库提问，并流式返回回答。 name: 查询 - description: 查看一次查询检索到了什么，以及原因。 name: 查询记录 - description: 在后台运行研究问题，并获取其结果。 name: 研究任务 - description: 读取知识库中的文档及其文件、修订版本和分段，并用元数据标注文档。 name: 文档与分段 - description: 跟踪、取消或重试索引，并列出知识库的后台任务。 name: 索引任务 - description: 跟踪文档文件、一批文件或数据源的删除，直到完成。 name: 删除作业 - description: 管理为知识库提供内容的数据源，以及它们的定时同步设置和连接。 name: 数据源 - description: 立即同步数据源，导入网站页面或提供商条目，并跟踪、取消或重试运行。 name: 数据源同步与导入 - description: 读取和更改知识库的模型与检索设置，并跟踪更改触发的迁移。 name: 设置 paths: /knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}: get: tags: - Indexing Tasks summary: 获取索引任务 description: >- 返回一个索引任务的状态。索引任务负责把文档文件的某个版本变成生效的修订版本。 轮询直到 `stage` 为 `published`、`failed` 或 `canceled`。`stage` 未变化时，可通过 `run_state` 判断任务是在等待（`queued`、`dispatch_pending`、`retry_wait`）还是正在运行（`running`）。重新索引流程详见 [重新索引并跟踪索引进度](/zh/api-reference/guides/knowledge-base#track-indexing)。 operationId: getIndexingTask parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- 索引任务 ID，以下各处出现的都是同一个值：[重新索引文档](/zh/api-reference/documents-and-chunks/re-index-documents) 响应中 `queued` 条目的 `compilation_job.id`、[获取文档](/zh/api-reference/documents-and-chunks/get-document) 返回的 `latest_task.id`、[获取文档的索引任务列表](/zh/api-reference/indexing-tasks/list-document-indexing-tasks) 返回的 `id`，以及 [获取后台任务列表](/zh/api-reference/indexing-tasks/list-background-tasks) 中 `document` 任务的 `id`。 in: path name: task_id required: true schema: format: uuid type: string responses: '200': content: application/json: examples: success: summary: 响应示例 value: base_head_revision: 1 candidate_fingerprint: null candidate_publication_id: null completed_at: null created_at: 1788681600000 document_asset_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b error: null execution_attempts: 1 failure: null id: e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b max_execution_attempts: 3 run_state: running stage: outline_built updated_at: 1788681645000 version: 1 schema: $ref: '#/components/schemas/KnowledgeBaseIndexingTask' description: 索引任务。 '400': content: application/json: examples: 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 description: '- `knowledge_fs_invalid_request`：`task_id` 格式不正确。' '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`：缺少 `Authorization` 请求头，或密钥无法识别、不是知识库 API 密钥。 - `knowledge_fs_invalid_credential`：密钥有效，但其所属工作空间中没有此 ID 的知识库，或该密钥未关联任何工作空间。 '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 (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_2: summary: knowledge_fs_access_denied (upstream) 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: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`：该密钥的访问范围限定为其他知识库、此知识库已关闭 **API 访问**，或知识库未处于活动状态。 - `knowledge_fs_access_denied`：该密钥无权访问此知识库的内容。 - `forbidden`：在 Dify Cloud 上，工作空间已达到其订阅套餐的知识库请求频率限制。所有调用都计入，读取操作也不例外。 '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`：不存在此 ID 的索引任务，或其索引的文档文件已无法用该密钥读取。 - `not_found`：当前部署已关闭 Agent 知识库功能。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: '- `knowledge_fs_upstream_unavailable`：未能及时收到响应，或无法读取响应。稍候重试。' '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`：此工作空间尚未配置 Agent 知识库功能、当前部署不提供此操作，或在请求鉴权期间该密钥对此知识库的访问权限发生了变化。 - `knowledge_fs_operation_unavailable`：暂时无法处理该请求。按 `failure.retryPolicy` 处理。 components: schemas: KnowledgeBaseIndexingTask: properties: base_head_revision: description: 内部字段，跟踪任务时无需使用。 nullable: true type: integer candidate_fingerprint: description: 内部字段，跟踪任务时无需使用。 nullable: true type: string candidate_publication_id: description: 内部字段，跟踪任务时无需使用。 nullable: true type: string completed_at: description: 任务进入终态阶段的时间，Unix 纪元毫秒。运行期间及重试后为 `null`。 nullable: true type: number created_at: description: 任务创建时间，Unix 纪元毫秒。 type: number document_asset_id: description: >- 正在索引的文档文件 ID，可用于 [获取文档文件](/zh/api-reference/documents-and-chunks/get-document-file)。该值为发起此任务的 [重新索引文档](/zh/api-reference/documents-and-chunks/re-index-documents) 请求项中的 `asset.id`，即使你提交的是文档 ID 也是如此。 type: string error: description: >- 简短的失败消息，可能与 `failure.message` 不同。仅当 `stage` 或 `run_state` 为 `failed` 时设置，其他情况下为 `null`，已取消的任务也是如此。 nullable: true type: string execution_attempts: description: >- 已执行的尝试次数。[重试索引任务](/zh/api-reference/indexing-tasks/retry-indexing-task) 会将其重置为 `0`，因此反复重试本身不会耗尽尝试次数上限。 nullable: true type: integer failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: 任务失败时的错误详情，否则为 `null`。 nullable: true id: description: 索引任务 ID。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string max_execution_attempts: description: 任务判定为失败前允许的尝试次数。 nullable: true type: integer run_state: description: >- 当前尝试的调度状态： - `dispatch_pending`：已受理，等待分派给工作进程。 - `queued`：已分派，等待工作进程处理。 - `running`：工作进程正在执行任务。 - `retry_wait`：已安排自动重试，`stage` 保持不变。 - `succeeded`：与 `stage: published` 同时出现。 - `failed`、`canceled`：终态。 - `superseded`：较新的一次尝试取代了本次尝试。属于终态，此时报告的阶段为 `stage: canceled`，取消和重试操作都不接受此状态的任务。 未设置时为 `null`。[重试索引任务](/zh/api-reference/indexing-tasks/retry-indexing-task) 会将其设为 `dispatch_pending`。 nullable: true type: string stage: description: >- 索引阶段，按推进顺序： - `queued` - `parsed` - `outline_built` - `nodes_generated` - `projection_built` - `smoke_eval_passed` - `published` `published` 表示新修订版本已生效。`failed` 和 `canceled` 是另外两个终态值。[重试索引任务](/zh/api-reference/indexing-tasks/retry-indexing-task) 会保留该次尝试已到达的检查点，因此重试后该值很少为 `queued`。 type: string updated_at: description: 任务最后变更时间，Unix 纪元毫秒。 type: number version: description: 正在索引的文档文件的版本。 type: integer type: object KnowledgeBaseErrorDetails: properties: action: description: >- 建议的下一步操作（如有）：`configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload` 或 `retry`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: string category: description: >- 失败类别：`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout` 或 `validation`。 type: string code: description: >- 稳定的错误码，采用大写蛇形命名，例如 `KNOWLEDGE_FS_CONFLICT` 或 `SOURCE_CREDENTIAL_TEST_FAILED`。 type: string message: description: 错误码或失败类别对应的公开消息。不会暴露提供商的错误详情。 type: string parameters: additionalProperties: true description: >- 描述失败细节的值，最多 8 个，键取自 `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds` 和 `status`。没有时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: object retryPolicy: description: >- 重试是否有用：`automatic`（服务会自动重试）、`manual`（需自行重试）、`after_configuration`（先在 Dify 中修正知识库配置）或 `never`（需修改请求）。 type: string stage: description: >- 失败所在的阶段，例如 `query_generation` 或 `credential-test`。不适用时为 `null`。HTTP 错误响应体中不包含此字段。 nullable: true type: string traceId: description: 联系管理员时需提供的参考编号。在包含失败详情的成功响应中可能为 `null`，在 HTTP 错误响应体中可能不出现。 nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.