Get Query Record
Returns one query record in full: the query, the retrieval depth, who ran it, and the pipeline steps in execution order with their metadata. The query.generate step’s metadata embeds every retrieved chunk, so the response can be large (up to 2 MiB).
Chunks from documents deleted since the run show as unavailable. For paginated views of the same chunks, use List Query Chunks, List Query Conflicts, and List Missing Chunks.
For the models and index versions the run used, read profile in List Query Records.
For how to read a run’s chunks, conflicts, and missing chunks together, see Investigate an Answer.
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
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).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path parameters
Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (
…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.Responses
application/json
The query record.
When the run was recorded, ISO 8601.
ID of the set of retrieved chunks the record refers to. No operation takes this ID. The chunks themselves are embedded in the
query.generate step. null when the run recorded none.Query record ID.
Internal ID of the knowledge base. Not the knowledge base ID in the path.
Retrieval depth of the run:
fast, deep, or research.The query text.
Images used in the original query, when present. Omitted for text-only queries.
Show child attributesHide child attributes
Who produced the record:
service_api, workflow, agent, mcp, or retrieval_test.Steps of the run, in execution order.
Show child attributesHide child attributes
When the step ended, ISO 8601.
null when not recorded.Step details. The available keys depend on the step. Handle additional metadata keys without assuming a fixed set.
Show child attributesHide child attributes
query.route: whether the depth decision fell back because the reasoning model's depth call failed.query.route: time the depth decision took, in milliseconds.query.generate: number of events the run recorded, including internal ones. Not the number of stream events sent.Recorded on the query.generate step. Find it by scanning steps[] for this key rather than by step name. The retrieved chunks the three list views are derived from.
Citation startOffset and endOffset values are zero-based UTF-8 byte offsets in parsed document text, with an inclusive start and exclusive end. These are not positions in the original file or answer.
Show child attributesHide child attributes
When the chunks were recorded, ISO 8601.
ID of this set of retrieved chunks.
The retrieved chunks, in the order the run ranked them.
Show child attributesHide child attributes
Where the chunk comes from. The first is the primary citation.
Show child attributesHide child attributes
Document file ID. To find its document, pass it with
documentVersion to Get Document by File.Document file version.
Heading path, outermost first.
Conflicts recorded on the chunk.
status (fresh, stale, unknown) and optional observedAt, sourceUpdatedAt.Free-form chunk metadata.
Chunk ID.
Relevance score, 0 to 1.
Score breakdown:
final, retrieval, and optional rerank, freshness.Chunk text.
Chunks the run expected but could not use.
Show child attributesHide child attributes
Chunk ID that was expected. Present when known.
Free-form record metadata.
not-retrieved, permission-filtered, stale, conflict, or unknown.
permission-filtered: An access check excluded the chunk.
What was missing. Only available here. The missing-chunks view omits it.
Query text the chunks answer.
answerable, partial, not-enough-evidence, conflict, or permission-limited.query.generate: why the run counts as a failed query: no-retrieval-evidence or low-confidence. Present only when queryOutcome is no-evidence or low-confidence. These runs still complete normally.query.generate: why generation stopped: retrieval-evidence when chunks were found, no-retrieval-evidence when nothing matched.query.retrieve: number of chunks the retrieval returned.query.generate: classification of the run, for example answered.query.route: the depth the caller asked for, or the knowledge base's default depth when the caller omitted mode. selectionSource tells the two apart.query.route: depth the run used: fast, deep, or research.query.route: how the depth was chosen, for example explicit when the request or the default named a depth.query.route: where the requested depth came from: request, profile-default, or legacy-default.Step name.
query.route is the depth decision and query.generate the answer summary. Between them the retrieval pipeline writes query.embed, query.retrieve, and query.answer.When the step started, ISO 8601.
ok, error, or skipped.