List Query Records

Lists the query records of a knowledge base, newest first. Each Run Query call saves a record once its stream opens, including a run that then fails, unless the client disconnected or the run failed with RETRIEVAL_EXECUTION_LEASE_LOST.

The list contains the records this key produced plus records produced by workflows, agents, MCP clients, and other API keys. A separate key for each tenant does not limit this list to that tenant’s runs. Retrieval tests run in Dify are never listed.

source is the only filter. Capture the x-query-run-id header of Run Query at query time to reach one run again.

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

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#

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_idstringrequired#

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.

Query parameters

cursorstring#

Cursor from the previous page's next_cursor.

Length: 1–1000

sourceenum<string>#

Return only records produced by one kind of caller: service_api for API keys, workflow for workflow nodes, agent or mcp for those clients. retrieval_test is accepted but returns no records through this API.

Options:retrieval_testworkflowservice_apiagentmcp

limitinteger#

Records per page.

Default: 50

Range: 1–100

Responses

application/json

One page of query records.

dataobject[]#

Query records, newest first.

Show child attributes

completedboolean#

true when the run answered, false when it failed. Every listed run has finished, so false never means still running.

created_atstring#

When the run was recorded, ISO 8601.

duration_msinteger#

Duration of the run in milliseconds. null when not recorded.

evidence_bundle_idstring#

ID of the set of retrieved chunks the record refers to. No operation takes this ID. The three chunk views take the query record ID. null when the run recorded none.

evidence_statestring#

How well the retrieved chunks support an answer: answerable, partial, not-enough-evidence, conflict, or permission-limited. null when the run recorded none.

final_scorenumber#

Highest final relevance score across the run's retrieved chunks, from 0 to 1. null when nothing was scored.

idstring#

Query record ID. Equals the x-query-run-id response header of the Run Query call that produced it.

modestring#

Retrieval depth of the run: fast, deep, or research.

open_bad_case_idstring#

ID of the unresolved bad case opened on this record under Quality in Dify. No operation in this API takes this ID. null when none is open.

profileobject#

Models and index versions in effect during the run. Each field is null when not recorded.

Show child attributes

embedding_modelstring#

Embedding model name.

embedding_vector_space_idstring#

ID of the vector space the embeddings live in.

projection_publication_idstring#

ID of the index publication the run searched. Compare it across records to see whether two runs searched the same index.

projection_versioninteger#

Version of that publication.

reasoning_modelstring#

Reasoning model name.

rerank_modelstring#

Rerank model name.

retrieval_profile_revisioninteger#

Revision of the knowledge base's retrieval settings at run time.

querystring#

The query text.

query_imagesobject[]#

Images used in the original query, when present. Omitted for text-only queries.

Show child attributes

byte_sizeinteger#

File size in bytes, or null when unavailable.

Range: >= 0

mime_typestring#

Media type, or null when unavailable.

namestring#

File name. May be null in Service API responses.

preview_urlstring#

Preview URL. May be null in Service API responses; do not depend on it to display the image.

upload_file_idstringrequired#

ID of the image file used in the original query.

result_countinteger#

Number of retrieved chunks the run returned.

scoresobject#

Highest score of each kind across the run's retrieved chunks, each from 0 to 1 or null when not computed.

Show child attributes

finalnumber#

Final score.

reranknumber#

Rerank score.

retrievalnumber#

Retrieval score.

sourcestring#

Who produced the record: service_api (API key callers, including this API), workflow (a workflow node), agent, mcp, or retrieval_test (a Dify retrieval test).

stagesobject[]#

Summaries of the run's recorded steps, in execution order: each step's name, status, and candidate count when available. Call Get Query Record with this record's ID for step metadata, including the depth decision and answer summary.

Show child attributes

candidate_countinteger#

Number of candidates the step recorded. Only Dify retrieval tests record it, so it is null on every other record.

namestring#

Step name, such as query.route, query.embed, query.retrieve, query.answer, or query.generate.

statusstring#

ok, error, or skipped.

next_cursorstring#

Cursor for the next page, or null on the last page. Send it back as cursor.

Run Query Get Query Record