List Chunks

Lists the chunks of one revision of a document, ordered by chunk ID rather than by position. Takes the document ID from List Documents, not the document file ID, plus the revision number.

To read chunks in document order, fetch every page and sort by ordinal.

Any revision can be listed, including a superseded one, as long as the document file version behind it still exists.

For how document IDs and document file IDs relate, see Browse Documents and Chunks.

1 min read

get/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions/{revision}/chunks

Request example

curl --request GET \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions/{revision}/chunks \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_id}/revisions/{revision}/chunks"
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}/documents/{document_id}/revisions/{revision}/chunks', {
  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}/documents/{document_id}/revisions/{revision}/chunks',
  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}/documents/{document_id}/revisions/{revision}/chunks"

	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}/documents/{document_id}/revisions/{revision}/chunks"))
    .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}/documents/{document_id}/revisions/{revision}/chunks')

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": [
    {
      "created_at": "2026-09-03T10:04:30Z",
      "document_id": "3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a",
      "document_revision": 2,
      "enabled": true,
      "end_offset": 5120,
      "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "kind": "chunk",
      "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
      "ordinal": 14,
      "parent_chunk_id": null,
      "parse_element_ids": [
        "el-40",
        "el-41"
      ],
      "section_path": [
        "3 Employment",
        "3.4 Termination"
      ],
      "start_offset": 4600,
      "text": "Either party may terminate this agreement with thirty days' written notice.",
      "token_count": 131,
      "user_metadata": {}
    }
  ],
  "next_cursor": null
}

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

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "code": "knowledge_fs_invalid_request",
  "failure": {
    "category": "validation",
    "code": "KNOWLEDGE_FS_INVALID_REQUEST",
    "message": "The Agent Knowledge Base request is invalid.",
    "retryPolicy": "never",
    "traceId": "7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83"
  },
  "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": "7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83"
  },
  "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",
  "failure": {
    "action": "contact_admin",
    "category": "internal",
    "code": "KNOWLEDGE_FS_INTERNAL_ERROR",
    "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
    "retryPolicy": "manual",
    "traceId": "5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b"
  },
  "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
  "status": 502
}

{
  "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}/documents/{document_id}/revisions/{revision}/chunks

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.

document_idstringrequired#

The document ID, from List Documents or from the address bar of the open document (/datasets/new/<knowledge base ID>/documents/<document ID>).

revisionintegerrequired#

Revision number. From List Document Revisions.

Range: >= 1

Query parameters

cursorstring#

Cursor from the previous page's next_cursor.

Length: 1–1000

querystring#

Case-insensitive substring to match against text. Not a semantic search. Omit it to list every chunk.

Length: 1–512

limitinteger#

Chunks per page.

Default: 50

Range: 1–100

Responses

application/json

One page of chunks.

dataobject[]#

One page of chunks, ordered by chunk ID.

Show child attributes

created_atstring#

When the chunk was created, ISO 8601.

document_idstring#

Document ID: the id of Get Document.

document_revisioninteger#

Revision the chunk belongs to. Each revision has its own chunks. A chunk ID is addressable only through its own revision.

enabledboolean#

Whether the chunk takes part in retrieval. No operation in this API changes it.

end_offsetinteger#

Zero-based UTF-8 byte offset in the parsed document text. Exclusive end. null when unknown.

idstring#

Chunk ID. The chunk_id path value for Get Chunk.

kindstring#

What the chunk was built from: chunk for a run of body text (the default), section for a heading section, table for a table, image for an image, summary for a generated summary.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

ordinalinteger#

Position of the chunk within the revision, starting at 0. Sort by it to read chunks in document order.

parent_chunk_idstring#

ID of the parent chunk for parent-child chunking. null for top-level chunks.

parse_element_idsstring[]#

IDs of the parsed elements the chunk was built from.

section_pathstring[]#

Headings from the document root to the chunk's section.

start_offsetinteger#

Zero-based UTF-8 byte offset in the parsed document text. Inclusive start. null when unknown.

textstring#

Chunk content.

token_countinteger#

Number of tokens in text.

user_metadataobject#

Metadata attached to the chunk. Free-form object.

next_cursorstring#

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

List Document Revisions Get Chunk