> ## 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. # List Query Records > Lists the query records of a knowledge base, newest first. Each [Run Query](/en/api-reference/queries/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](/en/api-reference/queries/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](/en/api-reference/guides/knowledge-base#investigate-an-answer). ## OpenAPI ````yaml /en/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/traces openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/traces: get: tags: - Query Records summary: List Query Records description: >- Lists the query records of a knowledge base, newest first. Each [Run Query](/en/api-reference/queries/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](/en/api-reference/queries/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](/en/api-reference/guides/knowledge-base#investigate-an-answer). operationId: listQueryRecords parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: Cursor from the previous page's `next_cursor`. in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: >- 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. in: query name: source required: false schema: enum: - retrieval_test - workflow - service_api - agent - mcp type: string - description: Records per page. in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: Response Example 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: Query records, newest first. items: properties: completed: description: >- `true` when the run answered, `false` when it failed. Every listed run has finished, so `false` never means still running. type: boolean created_at: description: When the run was recorded, ISO 8601. type: string duration_ms: description: >- Duration of the run in milliseconds. `null` when not recorded. nullable: true type: integer evidence_bundle_id: description: >- 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. nullable: true type: string evidence_state: description: >- How well the retrieved chunks support an answer: `answerable`, `partial`, `not-enough-evidence`, `conflict`, or `permission-limited`. `null` when the run recorded none. nullable: true type: string final_score: description: >- Highest final relevance score across the run's retrieved chunks, from 0 to 1. `null` when nothing was scored. nullable: true type: number id: description: >- Query record ID. Equals the `x-query-run-id` response header of the [Run Query](/en/api-reference/queries/run-query) call that produced it. type: string mode: description: >- Retrieval depth of the run: `fast`, `deep`, or `research`. type: string open_bad_case_id: description: >- 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. nullable: true type: string profile: description: >- Models and index versions in effect during the run. Each field is `null` when not recorded. properties: embedding_model: description: Embedding model name. nullable: true type: string embedding_vector_space_id: description: ID of the vector space the embeddings live in. nullable: true type: string projection_publication_id: description: >- ID of the index publication the run searched. Compare it across records to see whether two runs searched the same index. nullable: true type: string projection_version: description: Version of that publication. nullable: true type: integer reasoning_model: description: Reasoning model name. nullable: true type: string rerank_model: description: Rerank model name. nullable: true type: string retrieval_profile_revision: description: >- Revision of the knowledge base's retrieval settings at run time. nullable: true type: integer type: object query: description: The query text. type: string query_images: description: >- Images used in the original query, when present. Omitted for text-only queries. items: properties: byte_size: description: >- File size in bytes, or `null` when unavailable. minimum: 0 nullable: true type: integer mime_type: description: Media type, or `null` when unavailable. nullable: true type: string name: description: >- File name. May be `null` in Service API responses. nullable: true type: string preview_url: description: >- Preview URL. May be `null` in Service API responses; do not depend on it to display the image. nullable: true type: string upload_file_id: description: >- ID of the image file used in the original query. type: string required: - upload_file_id type: object type: array result_count: description: Number of retrieved chunks the run returned. type: integer scores: description: >- Highest score of each kind across the run's retrieved chunks, each from 0 to 1 or `null` when not computed. properties: final: description: Final score. nullable: true type: number rerank: description: Rerank score. nullable: true type: number retrieval: description: Retrieval score. nullable: true type: number type: object source: description: >- 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). type: string stages: description: >- Summaries of the run's recorded steps, in execution order: each step's name, status, and candidate count when available. Call [Get Query Record](/en/api-reference/query-records/get-query-record) with this record's ID for step metadata, including the depth decision and answer summary. items: properties: candidate_count: description: >- Number of candidates the step recorded. Only Dify retrieval tests record it, so it is `null` on every other record. nullable: true type: integer name: description: >- Step name, such as `query.route`, `query.embed`, `query.retrieve`, `query.answer`, or `query.generate`. type: string status: description: '`ok`, `error`, or `skipped`.' type: string type: object type: array type: object type: array next_cursor: description: >- Cursor for the next page, or `null` on the last page. Send it back as `cursor`. nullable: true type: string type: object description: One page of query records. '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`: the request failed validation. `violations` names each failing field. - `knowledge_fs_invalid_request`: `cursor` cannot be decoded. '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`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '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`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '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`: the knowledge base ID isn't recognized. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '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`: no answer came back in time, or the answer couldn't be read. Retry after a pause. '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`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. components: securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 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](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.