Get Bulk Task

Returns the progress of the indexing tasks in a bulk task. In this API a bulk task comes from Re-index Documents, and only the API key that started it can read it.

Items that Re-index Documents reported as not_found count as completed, so completed_items can equal total_items even when no document was re-indexed. Compare total_items with the number of queued items in that response to catch it. For the re-index flow, see Re-index and Track Indexing.

1 min read

get/knowledge-fs/spaces/{knowledge_base_id}/bulk-jobs/{bulk_task_id}

Request example

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

import requests

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

	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}/bulk-jobs/{bulk_task_id}"))
    .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}/bulk-jobs/{bulk_task_id}')

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

{
  "canceled_items": 0,
  "completed_items": 1,
  "created_at": "2026-09-06T02:30:00Z",
  "failed_item_ids": [],
  "failed_items": 0,
  "failures": [],
  "id": "c7d9e1f3-5a7b-4c9d-8e0f-1a2b3c4d5e6f",
  "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
  "status": "running",
  "total_items": 2,
  "type": "document_reindex",
  "updated_at": "2026-09-06T02:31:12Z"
}

{
  "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}/bulk-jobs/{bulk_task_id}

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.

bulk_task_idstringrequired#

Bulk task ID: bulk_job_id of the Re-index Documents response. List Background Tasks also returns it, as the id of a document_bulk task. The id of a document_delete task from Delete Document is a deletion job ID: follow it with Get Deletion Job.

Responses

application/json

The bulk task.

canceled_itemsinteger#

Items whose task was canceled, including documents that were disabled when the re-index was requested.

completed_itemsinteger#

Items that completed or were reported as not_found.

created_atstring#

When the bulk task was created, ISO 8601.

failed_item_idsstring[]#

IDs of the failed items, as submitted to Re-index Documents. They are not indexing task IDs. Map them to tasks with the items entries you kept from that response.

failed_itemsinteger#

Items whose task failed.

failuresobject[]#

One entry per failed item. Empty when none failed.

Show child attributes

document_idstring#

The item's ID, as submitted to Re-index Documents.

document_titlestring#

Title of the document. null when unknown.

error_codestring#

Failure code.

error_messagestring#

Failure message.

failureobject#

Error details. null when none were recorded.

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.

job_idstring#

ID of the item's job. null when none was recorded.

idstring#

Bulk task ID.

knowledge_space_idstring#

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

statusstring#

Aggregate state:

running: at least one item is still in progress.
completed: every item completed (reached at least projection_built, which comes before published) or was reported as not_found.
failed: every item is terminal and at least one failed.
canceled: every item is terminal, none failed, and at least one was canceled.

completed does not guarantee that the new revisions are active yet. When that matters, check each task with Get Indexing Task for stage: published, using the task IDs you kept from Re-index Documents.

total_itemsinteger#

Number of items submitted.

typestring#

document_reindex for bulk tasks from this API. document_upload and document_delete arise only from Dify operations. A deletion over this API answers with a deletion job, which is not a bulk task: follow it with Get Deletion Job or Get Deletion Batch.

updated_atstring#

Latest change across the bulk task and its indexing tasks, ISO 8601.

Retry Indexing Task List Document Indexing Tasks