> ## 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. # クエリ記録一覧を取得 > ナレッジベースのクエリ記録を新しい順に一覧表示します。[クエリを実行](/ja/api-reference/queries/run-query) の各呼び出しは、ストリームが開いた時点で記録を保存します。その後に失敗した実行も含まれますが、クライアントが切断した場合や、実行が `RETRIEVAL_EXECUTION_LEASE_LOST` で失敗した場合は保存されません。 一覧には、このキーで生成された記録に加え、ワークフロー、Agent、MCP クライアント、ほかの API キーで生成された記録も含まれます。テナントごとに別のキーを使っても、一覧がそのテナントの実行に限定されることはありません。Dify で実行した検索テストは一覧に含まれません。 フィルターは `source` のみです。特定の実行に後からアクセスするには、クエリ時に [クエリを実行](/ja/api-reference/queries/run-query) の `x-query-run-id` ヘッダーを記録しておいてください。 実行のチャンク、矛盾、欠落したチャンクをあわせて読み解く方法については、[回答の調査](/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 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: get: tags: - Query Records summary: クエリ記録一覧を取得 description: >- ナレッジベースのクエリ記録を新しい順に一覧表示します。[クエリを実行](/ja/api-reference/queries/run-query) の各呼び出しは、ストリームが開いた時点で記録を保存します。その後に失敗した実行も含まれますが、クライアントが切断した場合や、実行が `RETRIEVAL_EXECUTION_LEASE_LOST` で失敗した場合は保存されません。 一覧には、このキーで生成された記録に加え、ワークフロー、Agent、MCP クライアント、ほかの API キーで生成された記録も含まれます。テナントごとに別のキーを使っても、一覧がそのテナントの実行に限定されることはありません。Dify で実行した検索テストは一覧に含まれません。 フィルターは `source` のみです。特定の実行に後からアクセスするには、クエリ時に [クエリを実行](/ja/api-reference/queries/run-query) の `x-query-run-id` ヘッダーを記録しておいてください。 実行のチャンク、矛盾、欠落したチャンクをあわせて読み解く方法については、[回答の調査](/ja/api-reference/guides/knowledge-base#investigate-an-answer) を参照してください。 operationId: listQueryRecords parameters: - description: >- ナレッジベース ID です。ナレッジベースの **API アクセス** ダイアログに表示されるサービス API エンドポイントの最後のセグメント（`…/knowledge-fs/spaces/`）です。アドレスバーでは `/datasets/new/` の後のセグメントです。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: 前のページの `next_cursor` から取得したカーソルです。 in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: >- 特定の種類の呼び出し元で生成された記録のみを返します。API キーは `service_api`、ワークフローノードは `workflow`、Agent クライアントと MCP クライアントはそれぞれ `agent` と `mcp` です。`retrieval_test` も指定できますが、この API では記録は返されません。 in: query name: source required: false schema: enum: - retrieval_test - workflow - service_api - agent - mcp type: string - description: 1 ページあたりの記録数です。 in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: レスポンス例 value: data: - completed: true created_at: '2026-09-06T08:00:01.840000Z' duration_ms: 1840 evidence_bundle_id: 7d1f4c2e-8b3a-4e6d-9f0a-2b3c4d5e6f70 evidence_state: answerable final_score: 0.82 id: 3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e mode: fast open_bad_case_id: null profile: embedding_model: text-embedding-3-large embedding_vector_space_id: >- embedding-space-sha256:7b2e4c9a1d3f5e6071829a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f projection_publication_id: f0a2c4e6-8b0d-4f2a-9c4e-6a8b0c2d4e6f projection_version: 4 reasoning_model: gpt-4.1 rerank_model: bge-reranker-v2-m3 retrieval_profile_revision: 2 query: What is the refund window? result_count: 6 scores: final: 0.82 rerank: 0.85 retrieval: 0.71 source: service_api stages: - candidate_count: null name: query.route status: ok - candidate_count: null name: query.retrieve status: ok - candidate_count: null name: query.generate status: ok next_cursor: null schema: properties: data: description: クエリ記録です。新しい順に並びます。 items: properties: completed: description: >- 実行が回答した場合は `true`、失敗した場合は `false` です。一覧の実行はすべて終了しているため、`false` が実行中を意味することはありません。 type: boolean created_at: description: 実行が記録された日時（ISO 8601）です。 type: string duration_ms: description: 実行の所要時間（ミリ秒）です。記録されていない場合は `null` です。 nullable: true type: integer evidence_bundle_id: description: >- この記録が参照する、検索されたチャンクのセットの ID です。この ID を受け取る操作はありません。3 つのチャンクビューはクエリ記録 ID を受け取ります。実行で何も記録されなかった場合は `null` です。 nullable: true type: string evidence_state: description: >- 検索されたチャンクが回答をどの程度裏付けているかを示します。`answerable`、`partial`、`not-enough-evidence`、`conflict`、`permission-limited` のいずれかです。実行で何も記録されなかった場合は `null` です。 nullable: true type: string final_score: description: >- 実行で検索されたチャンクのうち、最も高い最終関連度スコアです（0〜1）。スコアが付けられなかった場合は `null` です。 nullable: true type: number id: description: >- クエリ記録 ID です。この記録を生成した [クエリを実行](/ja/api-reference/queries/run-query) 呼び出しのレスポンスヘッダー `x-query-run-id` と同じ値です。 type: string mode: description: 実行の検索の深度です。`fast`、`deep`、`research` のいずれかです。 type: string open_bad_case_id: description: >- Dify の **品質** で、この記録に対して作成された未解決の問題ケースの ID です。この API には、この ID を受け取る操作はありません。未解決のケースがない場合は `null` です。 nullable: true type: string profile: description: >- 実行時に有効だったモデルとインデックスのバージョンです。記録されていないフィールドは `null` になります。 properties: embedding_model: description: 埋め込みモデル名です。 nullable: true type: string embedding_vector_space_id: description: 埋め込みが格納されているベクトル空間の ID です。 nullable: true type: string projection_publication_id: description: >- 実行が検索したインデックスの公開版の ID です。記録間で比較すると、2 つの実行が同じインデックスを検索したかどうかがわかります。 nullable: true type: string projection_version: description: その公開版のバージョンです。 nullable: true type: integer reasoning_model: description: 推論モデル名です。 nullable: true type: string rerank_model: description: リランクモデル名です。 nullable: true type: string retrieval_profile_revision: description: 実行時点での、ナレッジベースの検索設定のリビジョンです。 nullable: true type: integer type: object 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: >- プレビュー URL です。サービス API のレスポンスでは `null` になる場合があるため、画像の表示にはこの値に頼らないでください。 nullable: true type: string upload_file_id: description: 元のクエリで使用された画像ファイルの ID です。 type: string required: - upload_file_id type: object type: array result_count: description: 実行が返した、検索されたチャンクの数です。 type: integer scores: description: >- 実行で検索されたチャンク全体での、種類ごとの最高スコアです。それぞれ 0〜1 の値で、計算されなかった場合は `null` です。 properties: final: description: 最終スコアです。 nullable: true type: number rerank: description: リランクスコアです。 nullable: true type: number retrieval: description: 検索スコアです。 nullable: true type: number type: object source: description: >- 記録の生成元です。`service_api`（この API を含む、API キーによる呼び出し元）、`workflow`（ワークフローノード）、`agent`、`mcp`、`retrieval_test`（Dify の検索テスト）のいずれかです。 type: string stages: description: >- 実行で記録されたステップの概要で、実行順に並びます。各ステップの名前、ステータス、候補数（ある場合）を含みます。深度の決定や回答の概要を含むステップのメタデータを取得するには、この記録の ID で [クエリ記録を取得](/ja/api-reference/query-records/get-query-record) を呼び出してください。 items: properties: candidate_count: description: >- ステップで記録された候補の数です。これを記録するのは Dify の検索テストだけなので、それ以外の記録ではすべて `null` です。 nullable: true type: integer name: description: >- ステップ名です。`query.route`、`query.embed`、`query.retrieve`、`query.answer`、`query.generate` などがあります。 type: string status: description: '`ok`、`error`、`skipped` のいずれかです。' type: string type: object type: array type: object type: array next_cursor: description: 次のページのカーソルです。最後のページでは `null` です。`cursor` として送り返してください。 nullable: true type: string type: object description: 1 ページ分のクエリ記録です。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request (local validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - source type: literal_error knowledge_fs_invalid_request_2: summary: knowledge_fs_invalid_request (upstream) 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 description: >- - `knowledge_fs_invalid_request`：リクエストが検証に失敗しました。`violations` には、問題のあるフィールドがそれぞれ示されます。 - `knowledge_fs_invalid_request`：`cursor` をデコードできません。 '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 value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`：キーのアクセス範囲がほかのナレッジベースに限定されているか、このナレッジベースで **API アクセス** がオフになっています。または、ナレッジベースがアクティブではありません。 - `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`：時間内に応答が返らなかったか、応答を読み取れませんでした。しばらく待ってから再試行してください。 '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` に従ってください。 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.