クエリ記録を取得
クエリ記録を 1 件、省略せずに返します。クエリ、検索の深度、実行元、およびパイプラインの各ステップ（実行順）とそのメタデータを含みます。query.generate ステップのメタデータには検索されたすべてのチャンクが埋め込まれているため、レスポンスが大きくなることがあります（最大 2 MiB）。
実行後に削除されたドキュメントのチャンクは、利用不可として表示されます。同じチャンクをページ単位で確認するには、クエリのチャンク一覧を取得、クエリの矛盾一覧を取得、欠落チャンク一覧を取得 を使用してください。
実行で使用されたモデルとインデックスのバージョンは、クエリ記録一覧を取得 の profile で確認できます。
実行のチャンク、矛盾、欠落したチャンクをあわせて読み解く方法については、回答の調査 を参照してください。
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
すべてのリクエストは API キーで認証します：Authorization: Bearer {API_KEY}。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（Dify API クイックスタート）。
キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP 401（unauthorized）で失敗します。
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[] からこのキーを探して見つけてください。3 つの一覧ビューの元になる、検索されたチャンクです。
引用の startOffset と endOffset の値は、解析済みドキュメントテキスト内の 0 始まりの UTF-8 バイトオフセットで、開始位置を含み、終了位置を含みません。元のファイルや回答内の位置ではありません。
Show child attributesHide child attributes
チャンクが記録された日時（ISO 8601）です。
検索されたチャンクのこのセットの ID です。
検索されたチャンクです。実行で順位付けされた順に並びます。
Show child attributesHide child attributes
チャンクの出典です。最初の要素が主な引用です。
Show child attributesHide child attributes
ドキュメントファイル ID です。対応するドキュメントを調べるには、この値を
documentVersion とともに ファイルからドキュメントを取得 に渡してください。ドキュメントファイルのバージョンです。
見出しのパスです。最上位の見出しから順に並びます。
チャンクに記録された矛盾です。
status（fresh、stale、unknown）と、任意の observedAt、sourceUpdatedAt です。自由形式のチャンクメタデータです。
チャンク ID です。
関連度スコアです（0〜1）。
スコアの内訳です。
final、retrieval、および任意の rerank、freshness を含みます。チャンクのテキストです。
実行で想定されていたものの、使用できなかったチャンクです。
Show child attributesHide child attributes
チャンクが回答の対象とするクエリのテキストです。
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 は回答の概要です。この 2 つの間に、検索パイプラインが query.embed、query.retrieve、query.answer を書き込みます。ステップが開始された日時（ISO 8601）です。
ok、error、skipped のいずれかです。