Assets Server REST API - Processes – Help Center

The Process API lets clients track and cancel long-running server processes.

Note: A process can be viewed or canceled only by a superuser or by the user who started it. Finished processes remain queryable only for a limited time (see section Process history & retention later in this article.)

Get process status API

GET POST /services/process/info

Returns the current status of a single process by its ID.

Parameters

Name	Type	Description	Example
processId	string	ID of the process to query, as returned when the process was started. Required.	ID of the process to query, as returned when the process was started. Required.

Result

The response is a ProcessInfo object.

Field	Type	Description
id	string	Unique process ID.
name	string	Process name.
load	string	Load category: NORMAL, HEAVY, or HEAVY_EXCLUSIVE.
user	string	Name of the user who started the process.
cancelable	boolean	Whether the process supports cancellation.
state	string	Current state (see Process states).
progress	number	Number of items processed so far. -1 means indeterminable.
total	number	Total number of items to process. -1 or 0 means indeterminable.
errorCount	number	Number of errors encountered. -1 means indeterminable.
details	string	Message describing the current step.
failureMessage	string	Exception message when the process failed; otherwise absent.
displayState	string	Progress state.
estimateTimeRemaining	string	Estimated time remaining, or 'done' when finished.
done	boolean	'true' once the process has finished.

Example

Running process:

{
  "id": "k3Jd9aQ2",
  "name": "Stats history cleanup",
  "load": "NORMAL",
  "user": "admin",
  "cancelable": true,
  "state": "RUNNING",
  "progress": 1200,
  "total": 5000,
  "errorCount": 0,
  "details": "Processing index stats-202104-r1",
  "displayState": "24.0%, 1,200 per minute, ETR: 3m 10s",
  "estimateTimeRemaining": "3m 10s",
  "done": false
}

Completed process:

{
  "id": "k3Jd9aQ2",
  "name": "Stats history cleanup",
  "load": "NORMAL",
  "user": "admin",
  "cancelable": true,
  "state": "COMPLETED",
  "progress": 5000,
  "total": 5000,
  "errorCount": 0,
  "details": "Done",
  "displayState": "COMPLETED, processed 5000 in 4m at 1,250 per minute",
  "estimateTimeRemaining": "done",
  "done": true
}

Cancel process API

POST /services/process/cancel

Cancels a running process.

Note: Cancellation only works if the process can be canceled (cancelable: true).

Parameters

Name	Type	Description	Example
processId	string	ID of the process to cancel. Required.	k3Jd9aQ2

Result

{ "status": "OK" }

Process states

State	Description
RUNNING	The process is currently executing.
COMPLETED	The process finished successfully with no errors.
COMPLETED_WITH_ERRORS	The process finished, but one or more items failed.
FAILED	The process aborted because of an error.
CANCELLED	The process was canceled by a user.

Process history & retention

When a process finishes it is moved from the active list into an in-memory history, where it stays queryable through the Get process status API.

The twelve most recently finished processes are kept in history

Process authorization (role required to start)

Superuser tools (ROLE_SUPERUSER)

Assets processing tool

Bulk Import
Index rescue filestore scan
Missing original index scan
Restore backup
Stats activity cleanup
Stats history cleanup
Stats index cleanup
Stats search cleanup
Stats usage cleanup

Data-admin tools (ROLE_DATA_ADMIN)

Asset duplicate cleanup

Standard user operations (ROLE_USER + permission)

AddAssetToCollection
Move folder contents
RemoveFolder
RemoveRelations
UpdateMetadataBulk
and others