> ## 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. # クエリ記録を取得 > クエリ記録を 1 件、省略せずに返します。クエリ、検索の深度、実行元、およびパイプラインの各ステップ（実行順）とそのメタデータを含みます。`query.generate` ステップのメタデータには検索されたすべてのチャンクが埋め込まれているため、レスポンスが大きくなることがあります（最大 2 MiB）。 実行後に削除されたドキュメントのチャンクは、利用不可として表示されます。同じチャンクをページ単位で確認するには、[クエリのチャンク一覧を取得](/ja/api-reference/query-records/list-query-chunks)、[クエリの矛盾一覧を取得](/ja/api-reference/query-records/list-query-conflicts)、[欠落チャンク一覧を取得](/ja/api-reference/query-records/list-missing-chunks) を使用してください。 実行で使用されたモデルとインデックスのバージョンは、[クエリ記録一覧を取得](/ja/api-reference/query-records/list-query-records) の `profile` で確認できます。 実行のチャンク、矛盾、欠落したチャンクをあわせて読み解く方法については、[回答の調査](/ja/api-reference/guides/knowledge-base#investigate-an-answer) を参照してください。 ## OpenAPI ````yaml /ja/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: >- クエリ記録を 1 件、省略せずに返します。クエリ、検索の深度、実行元、およびパイプラインの各ステップ（実行順）とそのメタデータを含みます。`query.generate` ステップのメタデータには検索されたすべてのチャンクが埋め込まれているため、レスポンスが大きくなることがあります（最大 2 MiB）。 実行後に削除されたドキュメントのチャンクは、利用不可として表示されます。同じチャンクをページ単位で確認するには、[クエリのチャンク一覧を取得](/ja/api-reference/query-records/list-query-chunks)、[クエリの矛盾一覧を取得](/ja/api-reference/query-records/list-query-conflicts)、[欠落チャンク一覧を取得](/ja/api-reference/query-records/list-missing-chunks) を使用してください。 実行で使用されたモデルとインデックスのバージョンは、[クエリ記録一覧を取得](/ja/api-reference/query-records/list-query-records) の `profile` で確認できます。 実行のチャンク、矛盾、欠落したチャンクをあわせて読み解く方法については、[回答の調査](/ja/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 です。[クエリを実行](/ja/api-reference/queries/run-query) のレスポンスヘッダー `x-query-run-id`、または [クエリ記録一覧を取得](/ja/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[]` からこのキーを探して見つけてください。3 つの一覧ビューの元になる、検索されたチャンクです。 引用の `startOffset` と `endOffset` の値は、解析済みドキュメントテキスト内の 0 始まりの UTF-8 バイトオフセットで、開始位置を含み、終了位置を含みません。元のファイルや回答内の位置ではありません。 properties: createdAt: description: チャンクが記録された日時（ISO 8601）です。 type: string id: description: 検索されたチャンクのこのセットの ID です。 type: string items: description: 検索されたチャンクです。実行で順位付けされた順に並びます。 items: properties: citations: description: チャンクの出典です。最初の要素が主な引用です。 items: properties: documentAssetId: description: >- ドキュメントファイル ID です。対応するドキュメントを調べるには、この値を `documentVersion` とともに [ファイルからドキュメントを取得](/ja/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: 2 つのチャンクが矛盾する理由です。 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` は回答の概要です。この 2 つの間に、検索パイプラインが `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 キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/api-reference/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.