List Missing Chunks

Lists the chunks a query run expected but could not use, one entry per chunk. An empty data with truncated: false means the run recorded none.

The entries carry the reason and the entry’s metadata, not the missing text. To read the text, use Get Query Record and inspect steps[].metadata.evidenceBundle.missingEvidence.

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/{query_record_id}/missing

Request example

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

import requests

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

	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/{query_record_id}/missing"))
    .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/{query_record_id}/missing')

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

{
  "consistency_class": null,
  "data": [
    {
      "kind": "resource",
      "metadata": {
        "availability": "available",
        "reason": "permission-filtered"
      },
      "name": "missing-1",
      "path": "/queries/3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e/missing/1",
      "resource_type": "evidence",
      "target_id": "d4c6e8a0-2b4d-4e6f-8a0c-2e4f6a8b0c2d",
      "version": null
    }
  ],
  "next_cursor": null,
  "path": "/queries/3c9e3b1a-2f0a-4b7d-9d3e-1f2a3b4c5d6e/missing",
  "preview": null,
  "truncated": false
}

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

{
  "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_request",
  "message": "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_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
}

{
  "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/{query_record_id}/missing

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

Query record ID: the x-query-run-id response header of Run Query, or id from List Query Records.

Query parameters

cursorstring#

Cursor from the previous page's next_cursor. Entries are addressed by offset, so 0 starts from the first entry.

Length: 1–1000

limitinteger#

Entries per page.

Default: 100

Range: 1–100

Responses

application/json

One page of missing-chunk entries:

name is missing-<n>.
target_id is the expected chunk ID when recorded, else the entry name.
resource_type is evidence.

consistency_classstring#

Always null in these views.

dataobject[]#

Entries of this page, in the order the run recorded them.

Show child attributes

kindstring#

Always resource for these views.

metadataobject#

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.

Show child attributes

availabilitystring#

available, or unavailable when the chunk was deleted or is no longer readable.

citationCountinteger#

Chunks view: number of citations on the chunk.

conflictCountinteger#

Chunks view: number of conflicts recorded on the chunk. 0 when the chunk is unavailable.

documentIdstring#

Chunks view: document file ID of the primary citation. Usable with Get Document File. Present only when the chunk has a citation.

documentVersioninteger#

Chunks view: version of that document file. Present only when the chunk has a citation.

freshnessobject#

Chunks view. How current the chunk was at retrieval time.

Show child attributes

observedAtstring#

When the chunk was last observed, ISO 8601. Present when known.

sourceUpdatedAtstring#

When the source last changed, ISO 8601. Present when known.

statusstring#

fresh, stale, or unknown.

nodeIdstring#

Conflicts view: ID of the chunk that holds the conflict.

reasonstring#

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.

scorenumber#

Chunks view: relevance score of the chunk, from 0 to 1.

scoresobject#

Chunks view: score breakdown, each from 0 to 1.

Show child attributes

finalnumber#

Final score after all stages.

freshnessnumber#

Freshness score. Present when computed.

reranknumber#

Rerank score. Present when a reranker ran.

retrievalnumber#

Retrieval score.

sectionPathstring[]#

Chunks view: heading path of the primary citation, outermost first. Present only when the chunk has a citation.

severitystring#

Conflicts view: info, warning, or blocking. blocking conflicts are the ones that keep the run from answering.

textstring#

Chunks view. Text of the chunk. A placeholder when the chunk is unavailable.

titlestring#

Chunks view: last element of sectionPath. Present only when sectionPath is not empty.

unavailableReasonstring#

Why the chunk is unavailable, for example evidence-unavailable. Present only when availability is unavailable.

namestring#

Entry name. Chunks view: the chunk ID. Conflicts view: conflict-<n>, numbered from 1 within the chunk. Missing-chunks view: missing-<n>, numbered from 1.

pathstring#

Internal path of the entry. Informational. This API does not serve it.

resource_typestring#

node in the chunks and conflicts views, evidence in the missing-chunks view.

target_idstring#

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.

versioninteger#

Always null in these views.

next_cursorstring#

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

pathstring#

Internal path of the view, for example /queries/<query_record_id>/evidence. Informational. This API does not serve it.

previewboolean#

Always null in these views.

truncatedboolean#

true when more entries exist beyond this page. Follow next_cursor to read them.

List Query Conflicts List Research Tasks