> ## 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. # Get Query Record > Returns one query record in full: the query, the retrieval depth, who ran it, and the pipeline steps in execution order with their metadata. The `query.generate` step's metadata embeds every retrieved chunk, so the response can be large (up to 2 MiB). Chunks from documents deleted since the run show as unavailable. For paginated views of the same chunks, use [List Query Chunks](/en/api-reference/query-records/list-query-chunks), [List Query Conflicts](/en/api-reference/query-records/list-query-conflicts), and [List Missing Chunks](/en/api-reference/query-records/list-missing-chunks). For the models and index versions the run used, read `profile` in [List Query Records](/en/api-reference/query-records/list-query-records). 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/{query_record_id} 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/{query_record_id}: get: tags: - Query Records summary: Get Query Record description: >- Returns one query record in full: the query, the retrieval depth, who ran it, and the pipeline steps in execution order with their metadata. The `query.generate` step's metadata embeds every retrieved chunk, so the response can be large (up to 2 MiB). Chunks from documents deleted since the run show as unavailable. For paginated views of the same chunks, use [List Query Chunks](/en/api-reference/query-records/list-query-chunks), [List Query Conflicts](/en/api-reference/query-records/list-query-conflicts), and [List Missing Chunks](/en/api-reference/query-records/list-missing-chunks). For the models and index versions the run used, read `profile` in [List Query Records](/en/api-reference/query-records/list-query-records). 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: getQueryRecord 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: >- Query record ID: the `x-query-run-id` response header of [Run Query](/en/api-reference/queries/run-query), or `id` from [List Query Records](/en/api-reference/query-records/list-query-records). in: path name: query_record_id required: true schema: format: uuid type: string responses: '200': content: application/json: examples: success: summary: Response Example 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: When the run was recorded, ISO 8601. type: string evidence_bundle_id: description: >- ID of the set of retrieved chunks the record refers to. No operation takes this ID. The chunks themselves are embedded in the `query.generate` step. `null` when the run recorded none. nullable: true type: string id: description: Query record ID. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string mode: description: 'Retrieval depth of the run: `fast`, `deep`, or `research`.' type: string 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: Always `null` in this API. nullable: true type: string preview_url: description: Always `null` in this API. 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 source: description: >- Who produced the record: `service_api`, `workflow`, `agent`, `mcp`, or `retrieval_test`. type: string steps: description: Steps of the run, in execution order. items: properties: ended_at: description: >- When the step ended, ISO 8601. `null` when not recorded. nullable: true type: string metadata: description: >- Step details. The available keys depend on the step. Handle additional metadata keys without assuming a fixed set. properties: degraded: description: >- `query.route`: whether the depth decision fell back because the reasoning model's depth call failed. type: boolean durationMs: description: >- `query.route`: time the depth decision took, in milliseconds. type: integer eventCount: description: >- `query.generate`: number of events the run recorded, including internal ones. Not the number of stream events sent. type: integer evidenceBundle: description: >- Recorded on the `query.generate` step. Find it by scanning `steps[]` for this key rather than by step name. The retrieved chunks the three list views are derived from. Citation `startOffset` and `endOffset` values are zero-based UTF-8 byte offsets in parsed document text, with an inclusive start and exclusive end. These are not positions in the original file or answer. properties: createdAt: description: When the chunks were recorded, ISO 8601. type: string id: description: ID of this set of retrieved chunks. type: string items: description: >- The retrieved chunks, in the order the run ranked them. items: properties: citations: description: >- Where the chunk comes from. The first is the primary citation. items: properties: documentAssetId: description: >- Document file ID. To find its document, pass it with `documentVersion` to [Get Document by File](/en/api-reference/documents-and-chunks/get-document-by-file). type: string documentVersion: description: Document file version. type: integer sectionPath: description: Heading path, outermost first. items: type: string type: array type: object type: array conflicts: description: Conflicts recorded on the chunk. items: properties: reason: description: Why the two chunks conflict. type: string severity: description: '`info`, `warning`, or `blocking`.' type: string withNodeId: description: >- Chunk ID it conflicts with. Present when known. type: string type: object type: array freshness: description: >- `status` (`fresh`, `stale`, `unknown`) and optional `observedAt`, `sourceUpdatedAt`. properties: observedAt: type: string sourceUpdatedAt: type: string status: type: string type: object metadata: description: Free-form chunk metadata. type: object nodeId: description: Chunk ID. type: string score: description: Relevance score, 0 to 1. type: number scores: description: >- Score breakdown: `final`, `retrieval`, and optional `rerank`, `freshness`. properties: final: type: number freshness: type: number rerank: type: number retrieval: type: number type: object text: description: Chunk text. type: string type: object type: array missingEvidence: description: Chunks the run expected but could not use. items: properties: expectedEvidenceId: description: >- Chunk ID that was expected. Present when known. type: string metadata: description: Free-form record metadata. type: object reason: description: >- `not-retrieved`, `permission-filtered`, `stale`, `conflict`, or `unknown`. `permission-filtered`: An access check excluded the chunk. type: string text: description: >- What was missing. Only available here. The missing-chunks view omits it. type: string type: object type: array query: description: Query text the chunks answer. type: string state: description: >- `answerable`, `partial`, `not-enough-evidence`, `conflict`, or `permission-limited`. type: string type: object failedQueryTrigger: description: >- `query.generate`: why the run counts as a failed query: `no-retrieval-evidence` or `low-confidence`. Present only when `queryOutcome` is `no-evidence` or `low-confidence`. These runs still complete normally. type: string finishReason: description: >- `query.generate`: why generation stopped: `retrieval-evidence` when chunks were found, `no-retrieval-evidence` when nothing matched. type: string itemCount: description: >- `query.retrieve`: number of chunks the retrieval returned. type: integer queryOutcome: description: >- `query.generate`: classification of the run, for example `answered`. type: string requestedMode: description: >- `query.route`: the depth the caller asked for, or the knowledge base's default depth when the caller omitted `mode`. `selectionSource` tells the two apart. type: string resolvedMode: description: >- `query.route`: depth the run used: `fast`, `deep`, or `research`. type: string resolver: description: >- `query.route`: how the depth was chosen, for example `explicit` when the request or the default named a depth. type: string selectionSource: description: >- `query.route`: where the requested depth came from: `request`, `profile-default`, or `legacy-default`. type: string type: object name: description: >- Step name. `query.route` is the depth decision and `query.generate` the answer summary. Between them the retrieval pipeline writes `query.embed`, `query.retrieve`, and `query.answer`. type: string started_at: description: When the step started, ISO 8601. type: string status: description: '`ok`, `error`, or `skipped`.' type: string type: object type: array type: object description: The query record. '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` is not a UUID. The body carries `failure` and can carry `violations`. - `knowledge_fs_invalid_request`: `query_record_id` is malformed. '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 (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`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the key has no access to this knowledge base's content. - `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`: no query record has this ID, the record belongs to another knowledge base, or the record points at retrieved chunks that are no longer stored. - `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. - `knowledge_fs_upstream_unavailable`: the query record is larger than 2 MiB. A retry fails the same way. '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`. - `knowledge_fs_operation_unavailable`: the knowledge base was upgraded from a classic knowledge base and is still disabling the documents that were disabled or archived there. Retry later. 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.