Get Deletion Job

Returns the progress of a deletion requested with Delete Document, Delete Document File, or Delete Source, or of one file in Delete Document Files in Batch. Poll it until run_state is completed or failed.

Only the API key that requested the deletion can read its job. The job stays readable after the deletion completes.

Get Document, Get Document File, or Get Source answers 404 for the deleted object from the moment the deletion is accepted. When a source is deleted with documents=keep, its documents are hidden while the job runs and come back when it completes, with source_id set to null. If the job fails, they stay hidden.

A failed deletion cannot be retried over this API.

For the deletion flow, see Delete Documents and Sources.

1 min read

get/knowledge-fs/spaces/{knowledge_base_id}/deletion-jobs/{deletion_job_id}

Request example

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

import requests

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

{
  "checkpoint": "completed",
  "completed_at": "2026-10-20T09:00:09Z",
  "created_at": "2026-10-20T09:00:00Z",
  "error": null,
  "id": "b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e",
  "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
  "mode": "cascade",
  "progress": null,
  "retry_at": null,
  "run_state": "completed",
  "target_id": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
  "target_type": "document",
  "updated_at": "2026-10-20T09:00:09Z"
}

{
  "checkpoint": "deleting_objects",
  "completed_at": null,
  "created_at": "2026-10-20T09:00:00Z",
  "error": {
    "code": "DURABLE_DELETION_ITEM_RETRY_WAIT",
    "message": "Durable deletion is waiting to retry external cleanup",
    "retryable": false
  },
  "id": "b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e",
  "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
  "mode": "keep",
  "progress": null,
  "retry_at": "2026-10-20T09:01:00Z",
  "run_state": "retry_wait",
  "target_id": "6f1c2b0e-3d0b-4a5e-9f4c-1c0e6a7b8d90",
  "target_type": "source",
  "updated_at": "2026-10-20T09:00:30Z"
}

{
  "checkpoint": "deleting_derived_data",
  "completed_at": null,
  "created_at": "2026-10-20T09:00:00Z",
  "error": null,
  "id": "b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e",
  "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
  "mode": "cascade",
  "progress": null,
  "retry_at": null,
  "run_state": "running",
  "target_id": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
  "target_type": "document",
  "updated_at": "2026-10-20T09:00:04Z"
}

{
  "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}/deletion-jobs/{deletion_job_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.

deletion_job_idstringrequired#

Deletion job ID: job.id from Delete Document, Delete Document File, or Delete Source, or the job.id of an accepted file in Delete Document Files in Batch or Get Deletion Batch. Their status_url points here.

Responses

application/json

The deletion job.

checkpointstring#

How far the deletion has progressed: requested (newly accepted), then quiescing, deleting_objects, deleting_derived_data, deleting_primary_data, and completed.

completed_atstring#

When the job completed, ISO 8601. null until then, and on a failed job.

created_atstring#

When the job was accepted, ISO 8601.

errorobject#

The last error, or null when there is none. It is also set while run_state is retry_wait, so read run_state, not error, to tell whether the job failed.

Show child attributes

codestring#

Code of the last error.

messagestring#

Public message for the last error. Internal error details are omitted.

retryableboolean#

true when run_state is failed. This API can't retry a failed deletion.

idstring#

Deletion job ID.

knowledge_space_idstring#

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

modestring#

How a source deletion treats the source's documents: cascade deletes them, keep keeps them. Ignore it on a deletion of a document file or a document.

progressobject#

Item counts of a multi-item deletion. Not populated by this API. Always null.

Show child attributes

completed_itemsinteger#

Items deleted so far.

current_item_kindstring#

Kind of the item being deleted.

total_itemsinteger#

Items to delete.

retry_atstring#

When the next automatic retry runs, ISO 8601. null when none is scheduled.

run_statestring#

Scheduler state:

dispatch_pending (newly accepted), queued, running: in progress.
retry_wait: an automatic retry is scheduled at retry_at.
completed: everything was removed.
failed: cleanup stopped, and the target stays hidden. It can't be retried.

target_idstring#

ID of the target: the document file ID for document, the document ID for logical_document, the source ID for source.

target_typestring#

What the job deletes: document for a document file, logical_document for a whole document, source for a source.

updated_atstring#

When the job last changed, ISO 8601.

List Background Tasks Get Deletion Batch