List Document Indexing Tasks

Lists a document’s indexing tasks from uploads and syncs, oldest first, each with its outcome. Failed and canceled tasks are included.

The newest task is on the last page. For the task running now, read latest_task on Get Document instead.

An unknown document ID, including a document file ID, answers 200 with an empty data. A page can hold fewer than limit tasks, so follow next_cursor until it is null.

For which task operation to use when, see Track Indexing.

1 min read

get/knowledge-fs/spaces/{knowledge_base_id}/logical-documents/{document_id}/processing-tasks

Request example

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

import requests

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

	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}/logical-documents/{document_id}/processing-tasks"))
    .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}/logical-documents/{document_id}/processing-tasks')

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": [
    {
      "active_operations": [
        "parse"
      ],
      "completed_at": "2026-09-03T10:03:40Z",
      "created_at": "2026-09-03T10:02:11Z",
      "document_id": "2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e",
      "document_revision": 1,
      "error_code": "DOCUMENT_COMPILATION_FAILED",
      "error_message": "The document could not be processed. Try again, or contact an administrator with the error reference.",
      "failure": {
        "action": "contact_admin",
        "category": "internal",
        "code": "DOCUMENT_COMPILATION_FAILED",
        "message": "Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference.",
        "parameters": null,
        "retryPolicy": "manual",
        "stage": "parsing",
        "traceId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
      },
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
      "phase": "parsing",
      "progress_percent": 0,
      "retry_at": null,
      "semantic_enrichment": {
        "error_code": null,
        "error_message": null,
        "failure": null,
        "nodes_completed": 0,
        "nodes_total": null,
        "provider_calls": null,
        "provider_calls_maximum": null,
        "state": "disabled",
        "updated_at": null
      },
      "stage": "queued",
      "state": "failed",
      "updated_at": "2026-09-03T10:03:40Z"
    },
    {
      "active_operations": [],
      "completed_at": "2026-10-20T08:16:05Z",
      "created_at": "2026-10-20T08:15:42Z",
      "document_id": "2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e",
      "document_revision": 2,
      "error_code": null,
      "error_message": null,
      "failure": null,
      "id": "c4e8a2f6-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
      "phase": "complete",
      "progress_percent": 100,
      "retry_at": null,
      "semantic_enrichment": {
        "error_code": null,
        "error_message": null,
        "failure": null,
        "nodes_completed": 0,
        "nodes_total": null,
        "provider_calls": null,
        "provider_calls_maximum": null,
        "state": "disabled",
        "updated_at": null
      },
      "stage": "published",
      "state": "succeeded",
      "updated_at": "2026-10-20T08:16:05Z"
    }
  ],
  "next_cursor": null
}

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

{
  "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_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": "7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83"
  },
  "message": "You do not have permission to perform this Agent Knowledge Base operation.",
  "status": 403
}

{
  "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}/logical-documents/{document_id}/processing-tasks

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.

Query parameters

cursorstring#

Cursor from the previous page's next_cursor.

Length: 1–1000

limitinteger#

Tasks per page.

Default: 50

Range: 1–100

Responses

application/json

One page of indexing tasks.

dataobject[]#

One page of indexing tasks, oldest first.

Show child attributes

active_operationsstring[]#

Operations under way in the current phase, such as parse, chunk, embedding, or publication.

completed_atstring#

When the task ended, ISO 8601. null while it runs.

created_atstring#

When the task was created, ISO 8601. Get Indexing Task reports the same task's times in epoch milliseconds.

document_idstring#

Document ID.

document_revisioninteger#

Revision this task builds.

error_codestring#

Error code when state is failed.

error_messagestring#

The message for error_code. Can differ from failure.message.

failureobject#

Error details when state is failed. stage is the phase the task failed in, and traceId is the task ID. null otherwise.

Show child attributes

actionstring#

Suggested next step, when there is one: configure_model, configure_parser, configure_source, contact_admin, reupload, or retry. null when not applicable; omitted from HTTP error bodies.

categorystring#

Kind of failure: authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.

codestring#

Stable error code in upper snake case, for example KNOWLEDGE_FS_CONFLICT or SOURCE_CREDENTIAL_TEST_FAILED.

messagestring#

Public message for the error code or failure category. Provider error details are not exposed.

parametersobject#

Up to 8 values that qualify the failure, with keys among attempt, currentRowVersion, documentCount, expectedRowVersion, fileSizeBytes, limit, maxFileSizeBytes, maxItems, modelType, providerKind, retryAfterSeconds, and status. null when there are none; omitted from HTTP error bodies.

retryPolicystring#

Whether a retry can help: automatic (the service retries on its own), manual (retry yourself), after_configuration (fix the knowledge base's setup in Dify first), or never (change the request).

stagestring#

Stage the failure belongs to, for example query_generation or credential-test. null when not applicable; omitted from HTTP error bodies.

traceIdstring#

Reference to quote when contacting an administrator. May be null in a successful response containing failure details, or omitted from an HTTP error body.

idstring#

Indexing task ID. The same ID works with Get Indexing Task, Cancel Indexing Task, and Retry Indexing Task.

knowledge_space_idstring#

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

phasestring#

What the task is doing: queued, parsing, outline_summary, chunking_indexing, graph_admission, publication, or complete.

progress_percentinteger#

Progress from 0 to 100, derived from stage.

retry_atstring#

When the automatic retry runs, ISO 8601. Set while state is retry_wait.

semantic_enrichmentobject#

Knowledge graph building after the revision publishes. Indexing finishes the knowledge graph before publishing, so it doesn't schedule this step. state is not_scheduled while the task runs and disabled once it has ended. nodes_completed stays 0.

Show child attributes

error_codestring#

Error code when state is failed.

error_messagestring#

The message for error_code. Can differ from failure.message.

failureobject#

Error details when state is failed. null otherwise.

Show child attributes

actionstring#

Suggested next step, when there is one: configure_model, configure_parser, configure_source, contact_admin, reupload, or retry. null when not applicable; omitted from HTTP error bodies.

categorystring#

Kind of failure: authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.

codestring#

Stable error code in upper snake case, for example KNOWLEDGE_FS_CONFLICT or SOURCE_CREDENTIAL_TEST_FAILED.

messagestring#

Public message for the error code or failure category. Provider error details are not exposed.

parametersobject#

retryPolicystring#

stagestring#

Stage the failure belongs to, for example query_generation or credential-test. null when not applicable; omitted from HTTP error bodies.

traceIdstring#

Reference to quote when contacting an administrator. May be null in a successful response containing failure details, or omitted from an HTTP error body.

nodes_completedinteger#

Knowledge graph nodes built: 0 until state is ready, then the same as nodes_total.

nodes_totalinteger#

Knowledge graph nodes to build. null until known.

provider_callsinteger#

Model calls made so far.

provider_calls_maximuminteger#

Most model calls knowledge graph building may make.

statestring#

not_scheduled, pending, running, ready, failed, or disabled.

updated_atstring#

When the enrichment last changed, ISO 8601.

stagestring#

Last checkpoint reached, in forward order: queued, parsed, outline_built, nodes_generated, projection_built, smoke_eval_passed, published. It stays at the last checkpoint when the task fails or is canceled, so read state for the outcome.

statestring#

Run state:

dispatch_pending, queued: waiting for a worker.
retry_wait: an automatic retry is scheduled at retry_at.
running: a worker is indexing.
succeeded: the revision is published and serves queries.
failed: see failure. Restart it with Retry Indexing Task.
canceled.
superseded: a newer attempt replaced this one.

succeeded, failed, canceled, and superseded are terminal.

updated_atstring#

When the task last changed, ISO 8601.

next_cursorstring#

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

Get Bulk Task Get Document Indexing Task