获取查询记录
1 min read
get/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}
Request example
curl --request GET \
--url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}"
headers = {
"Authorization": "Bearer <token>",
}
response = requests.request("GET", url, headers=headers)
print(response.text)const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}', {
method: 'GET',
headers: {
'Authorization': 'Bearer <token>'
}
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyResponse
{
"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"
}
]
}{
"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
}{
"code": "knowledge_fs_invalid_request",
"message": "Agent Knowledge Base request is invalid.",
"status": 400
}{
"code": "knowledge_fs_invalid_credential",
"message": "Invalid Agent Knowledge Base service credential.",
"status": 401
}{
"code": "unauthorized",
"message": "Access token is invalid",
"status": 401
}{
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
"status": 403
}{
"code": "knowledge_fs_access_denied",
"message": "Agent Knowledge Base operation is not allowed.",
"status": 403
}{
"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
}{
"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
}{
"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
}{
"code": "knowledge_fs_upstream_unavailable",
"message": "Agent Knowledge Base is unavailable.",
"status": 502
}{
"code": "knowledge_fs_operation_unavailable",
"message": "Agent Knowledge Base operation is not available.",
"status": 503
}{
"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
}get/knowledge-fs/spaces/{knowledge_base_id}/traces/{query_record_id}
Authorization
Path parameters
知识库 ID：即知识库 API 访问 对话框中所示服务 API 端点的最后一段（
…/knowledge-fs/spaces/<knowledge base ID>），也是地址栏中 /datasets/new/ 之后的那一段。Responses
application/json
查询记录。
运行的记录时间，ISO 8601 格式。
该记录所引用的检索分段集合的 ID。没有任何操作接受此 ID。分段本身内嵌在
query.generate 步骤中。运行未记录检索分段时为 null。查询记录 ID。
知识库的内部 ID，并非路径中的知识库 ID。
本次运行的检索深度：
fast、deep 或 research。查询文本。
原始查询中使用的图片（如有）。纯文本查询不返回此字段。
产生该记录的调用方：
service_api、workflow、agent、mcp 或 retrieval_test。本次运行的步骤，按执行顺序排列。
Show child attributesHide child attributes
步骤结束时间，ISO 8601 格式。未记录时为
null。步骤详情。可用的键因步骤而异。处理时应兼容额外的元数据键，不要假定键的集合固定不变。
Show child attributesHide child attributes
query.route：深度决策是否因推理模型的深度判断调用失败而回退。query.route：深度决策耗时，单位为毫秒。query.generate：本次运行记录的事件数，包括内部事件。并非流中发送的事件数。记录在 query.generate 步骤上。查找时遍历 steps[]，找出含有此键的步骤，不要按步骤名称查找。三个列表视图都由这些检索分段派生而来。
引用中的 startOffset 和 endOffset 是解析后文档文本中的 UTF-8 字节偏移量，从 0 开始计数，包含起点、不包含终点。它们不是原始文件或回答中的位置。
Show child attributesHide child attributes
记录这些分段的时间，ISO 8601 格式。
这组检索分段的 ID。
检索到的分段，按本次运行的排序先后排列。
Show child attributesHide child attributes
分段的出处。第一项为主引用。
该分段上记录的冲突。
status（fresh、stale、unknown），以及可选的 observedAt、sourceUpdatedAt。自由格式的分段元数据。
分段 ID。
相关性分数，0～1。
分数明细：
final、retrieval，以及可选的 rerank、freshness。分段文本。
本次运行预期使用但未能使用的分段。
这些分段所回答的查询文本。
answerable、partial、not-enough-evidence、conflict 或 permission-limited。query.generate：本次运行被计为失败查询的原因：no-retrieval-evidence 或 low-confidence。仅当 queryOutcome 为 no-evidence 或 low-confidence 时返回。这类运行仍会正常完成。query.generate：生成停止的原因：找到分段时为 retrieval-evidence，没有任何匹配时为 no-retrieval-evidence。query.retrieve：检索返回的分段数。query.generate：本次运行的分类，例如 answered。query.route：调用方请求的深度；调用方省略 mode 时为知识库的默认深度。可通过 selectionSource 区分这两种情况。query.route：本次运行实际使用的深度：fast、deep 或 research。query.route：深度的确定方式，例如请求或默认设置指定了深度时为 explicit。query.route：所请求深度的来源：request、profile-default 或 legacy-default。步骤名称。
query.route 是深度决策，query.generate 是回答摘要。在这两者之间，检索流水线会写入 query.embed、query.retrieve 和 query.answer。步骤开始时间，ISO 8601 格式。
ok、error 或 skipped。