Indexing Tasks

Retry Indexing Task

Restarts an indexing task whose run_state is failed or canceled under the same task ID and returns the updated task. Poll Get Indexing Task with the same ID afterwards.

To index the document again once the task is published, use Re-index Documents. For the re-index flow, see Re-index and Track Indexing.

An attempt with run_state: superseded cannot be retried, even though its stage is canceled. If you saved a newer task ID from a re-index response, poll that task.

POST

knowledge-fs

spaces

{knowledge_base_id}

jobs

{task_id}

retry

Retry Indexing Task

curl --request POST \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"

	req, _ := http.NewRequest("POST", 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))

}

require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "base_head_revision": 1,
  "candidate_fingerprint": null,
  "candidate_publication_id": null,
  "completed_at": null,
  "created_at": 1788681600000,
  "document_asset_id": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
  "error": null,
  "execution_attempts": 0,
  "failure": null,
  "id": "e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
  "max_execution_attempts": 3,
  "run_state": "dispatch_pending",
  "stage": "outline_built",
  "updated_at": 1788681800000,
  "version": 1
}

Authorizations

Authorization

string

header

required

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_id

string<uuid>

required

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.

task_id

string<uuid>

required

Indexing task ID, the same in every place it appears: compilation_job.id of a queued item in the Re-index Documents response, latest_task.id from Get Document, id from List Document Indexing Tasks, and the id of a document task in List Background Tasks.

Response

The restarted task. run_state is dispatch_pending, and error and completed_at are null.

base_head_revision

integer | null

Internal. Not needed to follow the task.

candidate_fingerprint

string | null

Internal. Not needed to follow the task.

candidate_publication_id

string | null

Internal. Not needed to follow the task.

completed_at

number | null

When the task reached a terminal stage, in epoch milliseconds. null while it runs and after a retry.

created_at

number

When the task was created, in epoch milliseconds.

document_asset_id

string

ID of the document file being indexed. Usable with Get Document File. It is the asset.id of the Re-index Documents item that started the task, even when you submitted a document ID.

error

string | null

Short failure message. Can differ from failure.message. Set only when stage or run_state is failed. Otherwise null, including on canceled tasks.

execution_attempts

integer | null

Attempts made so far. Retry Indexing Task resets it to 0, so repeated retries never exhaust the attempt budget on their own.

failure

object | null

Error details when the task failed. null otherwise.

Show child attributes

string

Indexing task ID.

knowledge_space_id

string

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

max_execution_attempts

integer | null

Attempts allowed before the task fails.

run_state

string | null

Scheduler state of the current attempt:

dispatch_pending: accepted, waiting to be dispatched to a worker.
queued: dispatched, waiting for a worker.
running: a worker is executing the task.
retry_wait: an automatic retry is scheduled, and stage stays unchanged.
succeeded: accompanies stage: published.
failed, canceled: terminal.
superseded: a newer attempt replaced this one. Terminal, reported with stage: canceled, and accepted by neither cancel nor retry.

null when not set. Retry Indexing Task sets it to dispatch_pending.

stage

string

Indexing stage, in forward order:

queued
parsed
outline_built
nodes_generated
projection_built
smoke_eval_passed
published

published means the new revision is active. failed and canceled are the other terminal values. Retry Indexing Task keeps the checkpoint the attempt had reached, so the value is rarely queued after a retry.

updated_at

number

When the task last changed, in epoch milliseconds.

version

integer

Version of the document file being indexed.

Retry Indexing Task

curl --request POST \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"

	req, _ := http.NewRequest("POST", 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))

}

require 'uri'
require 'net/http'

url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "base_head_revision": 1,
  "candidate_fingerprint": null,
  "candidate_publication_id": null,
  "completed_at": null,
  "created_at": 1788681600000,
  "document_asset_id": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
  "error": null,
  "execution_attempts": 0,
  "failure": null,
  "id": "e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "knowledge_space_id": "9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b",
  "max_execution_attempts": 3,
  "run_state": "dispatch_pending",
  "stage": "outline_built",
  "updated_at": 1788681800000,
  "version": 1
}

Guides

App APIs

Knowledge APIs

Retry Indexing Task

Authorizations

Path Parameters

Response