> ## 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. # 获取查询记录 > 返回一条完整的查询记录：查询内容、检索深度、调用方，以及按执行顺序排列的流水线步骤及其元数据。`query.generate` 步骤的元数据内嵌了所有检索分段，因此响应可能较大（最大 2 MiB）。 运行之后所属文档被删除的分段会显示为不可用。如需分页查看这些分段，使用 [获取查询分段列表](/zh/api-reference/query-records/list-query-chunks)、[获取查询冲突列表](/zh/api-reference/query-records/list-query-conflicts) 和 [获取缺失分段列表](/zh/api-reference/query-records/list-missing-chunks)。 本次运行所用的模型和索引版本，见 [获取查询记录列表](/zh/api-reference/query-records/list-query-records) 中的 `profile`。 如何结合查看一次运行的分段、冲突和缺失分段，详见 [排查回答](/zh/api-reference/guides/knowledge-base#investigate-an-answer)。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_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}/traces/{query_record_id}: get: tags: - Query Records summary: 获取查询记录 description: >- 返回一条完整的查询记录：查询内容、检索深度、调用方，以及按执行顺序排列的流水线步骤及其元数据。`query.generate` 步骤的元数据内嵌了所有检索分段，因此响应可能较大（最大 2 MiB）。 运行之后所属文档被删除的分段会显示为不可用。如需分页查看这些分段，使用 [获取查询分段列表](/zh/api-reference/query-records/list-query-chunks)、[获取查询冲突列表](/zh/api-reference/query-records/list-query-conflicts) 和 [获取缺失分段列表](/zh/api-reference/query-records/list-missing-chunks)。 本次运行所用的模型和索引版本，见 [获取查询记录列表](/zh/api-reference/query-records/list-query-records) 中的 `profile`。 如何结合查看一次运行的分段、冲突和缺失分段，详见 [排查回答](/zh/api-reference/guides/knowledge-base#investigate-an-answer)。 operationId: getQueryRecord 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/queries/run-query) 返回的 `x-query-run-id` 响应头，或 [获取查询记录列表](/zh/api-reference/query-records/list-query-records) 中的 `id`。 in: path name: query_record_id required: true schema: format: uuid type: string responses: '200': content: application/json: examples: success: summary: 响应示例 value: created_at: '2026-09-06T08:00:01.840000Z' evidence_bundle_id: 7d1f4c2e-8b3a-4e6d-9f0a-2b3c4d5e6f70 id: 3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mode: fast query: What is the refund window? source: service_api steps: - ended_at: '2026-09-06T08:00:00.050000Z' metadata: degraded: false durationMs: 0 requestedMode: fast resolvedMode: fast resolver: explicit selectionSource: request name: query.route started_at: '2026-09-06T08:00:00Z' status: ok - ended_at: '2026-09-06T08:00:00.900000Z' metadata: itemCount: 1 name: query.retrieve started_at: '2026-09-06T08:00:00.050000Z' status: ok - ended_at: '2026-09-06T08:00:01.840000Z' metadata: eventCount: 5 evidenceBundle: createdAt: '2026-09-06T08:00:00.900Z' id: 7d1f4c2e-8b3a-4e6d-9f0a-2b3c4d5e6f70 items: - citations: - documentAssetId: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b documentVersion: 1 sectionPath: - Policies - Refunds conflicts: [] freshness: observedAt: '2026-09-05T10:00:00.000Z' sourceUpdatedAt: '2026-08-30T12:00:00.000Z' status: fresh metadata: {} nodeId: a1f3c5e7-9b2d-4f6a-8c0e-1d2f3a4b5c6d score: 0.82 scores: final: 0.82 freshness: 0.9 rerank: 0.85 retrieval: 0.71 text: Refunds are issued within 14 days of purchase. missingEvidence: [] query: What is the refund window? state: answerable finishReason: retrieval-evidence queryOutcome: answered name: query.generate started_at: '2026-09-06T08:00:01.840000Z' status: ok schema: properties: created_at: description: 运行的记录时间，ISO 8601 格式。 type: string evidence_bundle_id: description: >- 该记录所引用的检索分段集合的 ID。没有任何操作接受此 ID。分段本身内嵌在 `query.generate` 步骤中。运行未记录检索分段时为 `null`。 nullable: true type: string id: description: 查询记录 ID。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string mode: description: 本次运行的检索深度：`fast`、`deep` 或 `research`。 type: string query: description: 查询文本。 type: string query_images: description: 原始查询中使用的图片（如有）。纯文本查询不返回此字段。 items: properties: byte_size: description: 文件大小（字节），无法获取时为 `null`。 minimum: 0 nullable: true type: integer mime_type: description: 媒体类型，无法获取时为 `null`。 nullable: true type: string name: description: 在此 API 中始终为 `null`。 nullable: true type: string preview_url: description: 在此 API 中始终为 `null`。 nullable: true type: string upload_file_id: description: 原始查询中所用图片文件的 ID。 type: string required: - upload_file_id type: object type: array source: description: >- 产生该记录的调用方：`service_api`、`workflow`、`agent`、`mcp` 或 `retrieval_test`。 type: string steps: description: 本次运行的步骤，按执行顺序排列。 items: properties: ended_at: description: 步骤结束时间，ISO 8601 格式。未记录时为 `null`。 nullable: true type: string metadata: description: 步骤详情。可用的键因步骤而异。处理时应兼容额外的元数据键，不要假定键的集合固定不变。 properties: degraded: description: '`query.route`：深度决策是否因推理模型的深度判断调用失败而回退。' type: boolean durationMs: description: '`query.route`：深度决策耗时，单位为毫秒。' type: integer eventCount: description: '`query.generate`：本次运行记录的事件数，包括内部事件。并非流中发送的事件数。' type: integer evidenceBundle: description: >- 记录在 `query.generate` 步骤上。查找时遍历 `steps[]`，找出含有此键的步骤，不要按步骤名称查找。三个列表视图都由这些检索分段派生而来。 引用中的 `startOffset` 和 `endOffset` 是解析后文档文本中的 UTF-8 字节偏移量，从 0 开始计数，包含起点、不包含终点。它们不是原始文件或回答中的位置。 properties: createdAt: description: 记录这些分段的时间，ISO 8601 格式。 type: string id: description: 这组检索分段的 ID。 type: string items: description: 检索到的分段，按本次运行的排序先后排列。 items: properties: citations: description: 分段的出处。第一项为主引用。 items: properties: documentAssetId: description: >- 文档文件 ID。如需查找对应的文档，将它与 `documentVersion` 一起传给 [按文件获取文档](/zh/api-reference/documents-and-chunks/get-document-by-file)。 type: string documentVersion: description: 文档文件版本。 type: integer sectionPath: description: 标题路径，从最外层开始。 items: type: string type: array type: object type: array conflicts: description: 该分段上记录的冲突。 items: properties: reason: description: 两个分段冲突的原因。 type: string severity: description: '`info`、`warning` 或 `blocking`。' type: string withNodeId: description: 与之冲突的分段 ID。已知时返回。 type: string type: object type: array freshness: description: >- `status`（`fresh`、`stale`、`unknown`），以及可选的 `observedAt`、`sourceUpdatedAt`。 properties: observedAt: type: string sourceUpdatedAt: type: string status: type: string type: object metadata: description: 自由格式的分段元数据。 type: object nodeId: description: 分段 ID。 type: string score: description: 相关性分数，0～1。 type: number scores: description: >- 分数明细：`final`、`retrieval`，以及可选的 `rerank`、`freshness`。 properties: final: type: number freshness: type: number rerank: type: number retrieval: type: number type: object text: description: 分段文本。 type: string type: object type: array missingEvidence: description: 本次运行预期使用但未能使用的分段。 items: properties: expectedEvidenceId: description: 预期的分段 ID。已知时返回。 type: string metadata: description: 自由格式的记录元数据。 type: object reason: description: >- `not-retrieved`、`permission-filtered`、`stale`、`conflict` 或 `unknown`。 `permission-filtered`：访问权限检查排除了该分段。 type: string text: description: 缺失的内容。仅在此处提供，缺失分段视图中不包含此字段。 type: string type: object type: array query: description: 这些分段所回答的查询文本。 type: string state: description: >- `answerable`、`partial`、`not-enough-evidence`、`conflict` 或 `permission-limited`。 type: string type: object failedQueryTrigger: description: >- `query.generate`：本次运行被计为失败查询的原因：`no-retrieval-evidence` 或 `low-confidence`。仅当 `queryOutcome` 为 `no-evidence` 或 `low-confidence` 时返回。这类运行仍会正常完成。 type: string finishReason: description: >- `query.generate`：生成停止的原因：找到分段时为 `retrieval-evidence`，没有任何匹配时为 `no-retrieval-evidence`。 type: string itemCount: description: '`query.retrieve`：检索返回的分段数。' type: integer queryOutcome: description: '`query.generate`：本次运行的分类，例如 `answered`。' type: string requestedMode: description: >- `query.route`：调用方请求的深度；调用方省略 `mode` 时为知识库的默认深度。可通过 `selectionSource` 区分这两种情况。 type: string resolvedMode: description: >- `query.route`：本次运行实际使用的深度：`fast`、`deep` 或 `research`。 type: string resolver: description: >- `query.route`：深度的确定方式，例如请求或默认设置指定了深度时为 `explicit`。 type: string selectionSource: description: >- `query.route`：所请求深度的来源：`request`、`profile-default` 或 `legacy-default`。 type: string type: object name: description: >- 步骤名称。`query.route` 是深度决策，`query.generate` 是回答摘要。在这两者之间，检索流水线会写入 `query.embed`、`query.retrieve` 和 `query.answer`。 type: string started_at: description: 步骤开始时间，ISO 8601 格式。 type: string status: description: '`ok`、`error` 或 `skipped`。' type: string type: object type: array type: object description: 查询记录。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request 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: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: The Agent Knowledge Base request is invalid. status: 400 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`：`query_record_id` 不是 UUID。响应体包含 `failure`，还可能包含 `violations`。 - `knowledge_fs_invalid_request`：`query_record_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`：未能及时收到响应，或无法读取响应。稍候重试。 - `knowledge_fs_upstream_unavailable`：查询记录超过 2 MiB。重试也会同样失败。 '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` 处理。 - `knowledge_fs_operation_unavailable`：该知识库由经典知识库升级而来，仍在禁用原先已禁用或已归档的文档。稍后重试。 components: 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.