クエリ記録一覧を取得

ナレッジベースのクエリ記録を新しい順に一覧表示します。クエリを実行の各呼び出しは、ストリームが開いた時点で記録を保存します。その後に失敗した実行も含まれますが、クライアントが切断した場合や、実行が RETRIEVAL_EXECUTION_LEASE_LOST で失敗した場合は保存されません。

一覧には、このキーで生成された記録に加え、ワークフロー、Agent、MCP クライアント、ほかの API キーで生成された記録も含まれます。テナントごとに別のキーを使っても、一覧がそのテナントの実行に限定されることはありません。Dify で実行した検索テストは一覧に含まれません。

フィルターは source のみです。特定の実行に後からアクセスするには、クエリ時にクエリを実行の x-query-run-id ヘッダーを記録しておいてください。

実行のチャンク、矛盾、欠落したチャンクをあわせて読み解く方法については、回答の調査を参照してください。

1 min read

get/knowledge-fs/spaces/{knowledge_base_id}/traces

Request example

curl --request GET \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/traces"
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', {
  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',
  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"

	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"))
    .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')

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_body

Response

{
  "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
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "source"
      ],
      "type": "literal_error"
    }
  ]
}

{
  "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_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_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

Authorization

Authorizationstringheaderrequired#

すべてのリクエストは API キーで認証します：Authorization: Bearer {API_KEY}。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（Dify API クイックスタート）。

キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP 401（unauthorized）で失敗します。

Path parameters

knowledge_base_idstringrequired#

ナレッジベース ID です。ナレッジベースの API アクセス ダイアログに表示されるサービス API エンドポイントの最後のセグメント（…/knowledge-fs/spaces/<knowledge base ID>）です。アドレスバーでは /datasets/new/ の後のセグメントです。

Query parameters

cursorstring#

前のページの next_cursor から取得したカーソルです。

Length: 1–1000

sourceenum<string>#

特定の種類の呼び出し元で生成された記録のみを返します。API キーは service_api、ワークフローノードは workflow、Agent クライアントと MCP クライアントはそれぞれ agent と mcp です。retrieval_test も指定できますが、この API では記録は返されません。

Options:retrieval_testworkflowservice_apiagentmcp

limitinteger#

1 ページあたりの記録数です。

Default: 50

Range: 1–100

Responses

application/json

1 ページ分のクエリ記録です。

dataobject[]#

クエリ記録です。新しい順に並びます。

Show child attributes

completedboolean#

実行が回答した場合は true、失敗した場合は false です。一覧の実行はすべて終了しているため、false が実行中を意味することはありません。

created_atstring#

実行が記録された日時（ISO 8601）です。

duration_msinteger#

実行の所要時間（ミリ秒）です。記録されていない場合は null です。

evidence_bundle_idstring#

この記録が参照する、検索されたチャンクのセットの ID です。この ID を受け取る操作はありません。3 つのチャンクビューはクエリ記録 ID を受け取ります。実行で何も記録されなかった場合は null です。

evidence_statestring#

検索されたチャンクが回答をどの程度裏付けているかを示します。answerable、partial、not-enough-evidence、conflict、permission-limited のいずれかです。実行で何も記録されなかった場合は null です。

final_scorenumber#

実行で検索されたチャンクのうち、最も高い最終関連度スコアです（0〜1）。スコアが付けられなかった場合は null です。

idstring#

クエリ記録 ID です。この記録を生成したクエリを実行呼び出しのレスポンスヘッダー x-query-run-id と同じ値です。

modestring#

実行の検索の深度です。fast、deep、research のいずれかです。

open_bad_case_idstring#

Dify の品質で、この記録に対して作成された未解決の問題ケースの ID です。この API には、この ID を受け取る操作はありません。未解決のケースがない場合は null です。

profileobject#

実行時に有効だったモデルとインデックスのバージョンです。記録されていないフィールドは null になります。

Show child attributes

embedding_modelstring#

埋め込みモデル名です。

embedding_vector_space_idstring#

埋め込みが格納されているベクトル空間の ID です。

projection_publication_idstring#

実行が検索したインデックスの公開版の ID です。記録間で比較すると、2 つの実行が同じインデックスを検索したかどうかがわかります。

projection_versioninteger#

その公開版のバージョンです。

reasoning_modelstring#

推論モデル名です。

rerank_modelstring#

リランクモデル名です。

retrieval_profile_revisioninteger#

実行時点での、ナレッジベースの検索設定のリビジョンです。

querystring#

クエリのテキストです。

query_imagesobject[]#

元のクエリで使用された画像です（ある場合）。テキストのみのクエリでは省略されます。

Show child attributes

byte_sizeinteger#

ファイルサイズ（バイト）です。取得できない場合は null です。

Range: >= 0

mime_typestring#

メディアタイプです。取得できない場合は null です。

namestring#

ファイル名です。サービス API のレスポンスでは null になる場合があります。

preview_urlstring#

プレビュー URL です。サービス API のレスポンスでは null になる場合があるため、画像の表示にはこの値に頼らないでください。

upload_file_idstringrequired#

元のクエリで使用された画像ファイルの ID です。

result_countinteger#

実行が返した、検索されたチャンクの数です。

scoresobject#

実行で検索されたチャンク全体での、種類ごとの最高スコアです。それぞれ 0〜1 の値で、計算されなかった場合は null です。

Show child attributes

finalnumber#

最終スコアです。

reranknumber#

リランクスコアです。

retrievalnumber#

検索スコアです。

sourcestring#

記録の生成元です。service_api（この API を含む、API キーによる呼び出し元）、workflow（ワークフローノード）、agent、mcp、retrieval_test（Dify の検索テスト）のいずれかです。

stagesobject[]#

実行で記録されたステップの概要で、実行順に並びます。各ステップの名前、ステータス、候補数（ある場合）を含みます。深度の決定や回答の概要を含むステップのメタデータを取得するには、この記録の ID でクエリ記録を取得を呼び出してください。

Show child attributes

candidate_countinteger#

ステップで記録された候補の数です。これを記録するのは Dify の検索テストだけなので、それ以外の記録ではすべて null です。

namestring#

ステップ名です。query.route、query.embed、query.retrieve、query.answer、query.generate などがあります。

statusstring#

ok、error、skipped のいずれかです。

next_cursorstring#

次のページのカーソルです。最後のページでは null です。cursor として送り返してください。

クエリを実行クエリ記録を取得