> ## 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 Chunks > Lists the chunks a query run retrieved, one entry per chunk, with its primary citation, scores, freshness, and text. Entries are in the order the run ranked them. An empty `data` with `truncated: false` means the run recorded no chunks. 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}/evidence 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}/evidence: get: tags: - Query Records summary: List Query Chunks description: >- Lists the chunks a query run retrieved, one entry per chunk, with its primary citation, scores, freshness, and text. Entries are in the order the run ranked them. An empty `data` with `truncated: false` means the run recorded no chunks. 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: listQueryChunks 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 - description: >- Cursor from the previous page's `next_cursor`. Entries are addressed by offset, so `0` starts from the first entry. in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: Entries per page. in: query name: limit required: false schema: default: 100 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: Response Example value: consistency_class: null data: - kind: resource metadata: availability: available citationCount: 1 conflictCount: 1 documentId: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b documentVersion: 1 freshness: observedAt: '2026-09-05T10:00:00.000Z' sourceUpdatedAt: '2026-08-30T12:00:00.000Z' status: fresh score: 0.82 scores: final: 0.82 freshness: 0.9 rerank: 0.85 retrieval: 0.71 sectionPath: - Policies - Refunds text: Refunds are issued within 14 days of purchase. title: Refunds name: a1f3c5e7-9b2d-4f6a-8c0e-1d2f3a4b5c6d path: >- /queries/3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e/evidence/a1f3c5e7-9b2d-4f6a-8c0e-1d2f3a4b5c6d resource_type: node target_id: a1f3c5e7-9b2d-4f6a-8c0e-1d2f3a4b5c6d version: null - kind: resource metadata: availability: unavailable citationCount: 1 conflictCount: 0 documentId: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b documentVersion: 1 freshness: status: unknown score: 0.64 scores: final: 0.64 retrieval: 0.6 sectionPath: [] text: Evidence deleted or unavailable unavailableReason: evidence-unavailable name: b2e4d6f8-0c3e-4a7b-9d1f-2e3a4b5c6d7e path: >- /queries/3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e/evidence/b2e4d6f8-0c3e-4a7b-9d1f-2e3a4b5c6d7e resource_type: node target_id: b2e4d6f8-0c3e-4a7b-9d1f-2e3a4b5c6d7e version: null next_cursor: null path: /queries/3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e/evidence preview: null truncated: false schema: $ref: '#/components/schemas/KnowledgeBaseQueryRecordEntries' description: >- One page of chunk entries. `name` and `target_id` are the chunk's ID, and `resource_type` is `node`. '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: - cursor type: string_too_long 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 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`: the request failed validation, `limit` is above 100, or `query_record_id` is not a UUID. `violations` names each failing field. - `knowledge_fs_invalid_request`: `query_record_id` is malformed. - `knowledge_fs_invalid_request`: `cursor` is not a non-negative integer offset. '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. '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: schemas: KnowledgeBaseQueryRecordEntries: properties: consistency_class: description: Always `null` in these views. nullable: true type: string data: description: Entries of this page, in the order the run recorded them. items: properties: kind: description: Always `resource` for these views. type: string metadata: description: >- Details of the entry. The available keys depend on the view. In the missing-chunks view, `metadata` also carries the missing item's own metadata keys. properties: availability: description: >- `available`, or `unavailable` when the chunk was deleted or is no longer readable. type: string citationCount: description: 'Chunks view: number of citations on the chunk.' type: integer conflictCount: description: >- Chunks view: number of conflicts recorded on the chunk. `0` when the chunk is unavailable. type: integer documentId: description: >- Chunks view: document file ID of the primary citation. Usable with [Get Document File](/en/api-reference/documents-and-chunks/get-document-file). Present only when the chunk has a citation. type: string documentVersion: description: >- Chunks view: version of that document file. Present only when the chunk has a citation. type: integer freshness: description: Chunks view. How current the chunk was at retrieval time. properties: observedAt: description: >- When the chunk was last observed, ISO 8601. Present when known. type: string sourceUpdatedAt: description: >- When the source last changed, ISO 8601. Present when known. type: string status: description: '`fresh`, `stale`, or `unknown`.' type: string type: object nodeId: description: 'Conflicts view: ID of the chunk that holds the conflict.' type: string reason: description: >- Conflicts view: free-text explanation of the conflict. Missing-chunks view: why the chunk was not used, one of `not-retrieved`, `permission-filtered`, `stale`, `conflict`, or `unknown`. `permission-filtered`: An access check excluded the chunk. type: string score: description: 'Chunks view: relevance score of the chunk, from 0 to 1.' type: number scores: description: 'Chunks view: score breakdown, each from 0 to 1.' properties: final: description: Final score after all stages. type: number freshness: description: Freshness score. Present when computed. type: number rerank: description: Rerank score. Present when a reranker ran. type: number retrieval: description: Retrieval score. type: number type: object sectionPath: description: >- Chunks view: heading path of the primary citation, outermost first. Present only when the chunk has a citation. items: type: string type: array severity: description: >- Conflicts view: `info`, `warning`, or `blocking`. `blocking` conflicts are the ones that keep the run from answering. type: string text: description: >- Chunks view. Text of the chunk. A placeholder when the chunk is unavailable. type: string title: description: >- Chunks view: last element of `sectionPath`. Present only when `sectionPath` is not empty. type: string unavailableReason: description: >- Why the chunk is unavailable, for example `evidence-unavailable`. Present only when `availability` is `unavailable`. type: string type: object name: description: >- Entry name. Chunks view: the chunk ID. Conflicts view: `conflict-`, numbered from 1 within the chunk. Missing-chunks view: `missing-`, numbered from 1. type: string path: description: >- Internal path of the entry. Informational. This API does not serve it. type: string resource_type: description: >- `node` in the chunks and conflicts views, `evidence` in the missing-chunks view. nullable: true type: string target_id: description: >- The entry's target: - Chunks view: the chunk ID. - Conflicts view: the chunk it conflicts with, or its own chunk ID when none is recorded. - Missing-chunks view: the expected chunk ID when recorded, else the entry `name`. May not resolve to a live chunk when `metadata.availability` is `unavailable`. nullable: true type: string version: description: Always `null` in these views. nullable: true type: integer 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 path: description: >- Internal path of the view, for example `/queries//evidence`. Informational. This API does not serve it. type: string preview: description: Always `null` in these views. nullable: true type: boolean truncated: description: >- `true` when more entries exist beyond this page. Follow `next_cursor` to read them. type: boolean type: object 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.