Get backup progress

GetBackupProgress

GetBackupProgress

Description: Returns the latest backup progress snapshot.

Use this method to render a progress bar while StartFullBackup is running. The same data model is also pushed through the backup.progress stream channel.

Access Control

SESSION_ADMIN, SESSION_MANAGER

Request Parameters

No request parameters.

Request Example

{
  "command": "GetBackupProgress",
  "extID": "1",
  "data": {}
}

Response Data

Returns a flat backup progress object. The response is not wrapped in a nested data object.

Field	Type	Description
active	bool	true while a backup run is active
run_id	string	Current or last backup run identifier
type	string	Backup type: full or scoped
trigger	string	Trigger value: manual, cron, pre_update, or shutdown
status	string	Run status: running, completed, partial, failed, cancelled, or timeout
phase	string	Runtime phase, for example backup, validate, finalize, publish_remote, done, or failed
message	string	Human-readable progress message
current_participant	string	Participant currently being processed, if any
overall_percent	int	Overall progress from 0 to 100
participants_total	int	Number of participants in the run
participants_done	int	Number of completed participant steps
remote_total	int	Number of remote upload steps planned for enabled backup servers
remote_done	int	Number of completed remote upload steps
started_at	int	Unix timestamp when the run started
updated_at	int	Unix timestamp of the last progress update
finished_at	int	Unix timestamp when the run finished, or 0 while active
participants	array	Per-participant progress records

Participant progress fields:

Field	Type	Description
name	string	Participant name
status	string	pending, running, completed, or failed
phase	string	Participant phase, for example backup, validate, completed, or failed
percent	int	Participant progress from 0 to 100
message	string	Participant progress message or error text
artifacts	int	Number of artifacts produced by this participant
size_bytes	int	Total artifact size in bytes
started_at	int	Unix timestamp when participant processing started
finished_at	int	Unix timestamp when participant processing finished

Response Example

{
  "active": true,
  "run_id": "20260701-141500-000001",
  "type": "full",
  "trigger": "manual",
  "status": "running",
  "phase": "backup",
  "message": "dumping accounts",
  "current_participant": "accounts",
  "overall_percent": 40,
  "participants_total": 4,
  "participants_done": 1,
  "remote_total": 0,
  "remote_done": 0,
  "started_at": 1782915300,
  "updated_at": 1782915480,
  "finished_at": 0,
  "participants": [
    {
      "name": "symbols",
      "status": "completed",
      "phase": "completed",
      "percent": 100,
      "message": "",
      "artifacts": 1,
      "size_bytes": 327680,
      "started_at": 1782915300,
      "finished_at": 1782915360
    },
    {
      "name": "accounts",
      "status": "running",
      "phase": "backup",
      "percent": 10,
      "message": "dumping",
      "artifacts": 0,
      "size_bytes": 0,
      "started_at": 1782915480,
      "finished_at": 0
    }
  ]
}

After a successful backup finishes, polling returns an idle state instead of the last successful run:

{
  "active": false,
  "run_id": "",
  "type": "full",
  "trigger": "manual",
  "status": "completed",
  "phase": "idle",
  "message": "no active backup",
  "current_participant": "",
  "overall_percent": 0,
  "participants_total": 0,
  "participants_done": 0,
  "remote_total": 0,
  "remote_done": 0,
  "started_at": 0,
  "updated_at": 1782915790,
  "finished_at": 0,
  "participants": []
}

Stream Updates

Subscribe to the backup.progress channel to receive progress updates without polling. The TCP subscription request uses the existing misspelled chanels field name. channels is not accepted by the current TCP server.

{
  "command": "Subscribe",
  "extID": "sub-backup-progress",
  "data": {
    "chanels": ["backup.progress"]
  }
}

The subscription must be active before the backup run publishes progress. Because StartFullBackup is synchronous, use a second TCP or WebSocket session for the subscription while another session is waiting for StartFullBackup to return.

The server publishes the event through EventBus as channel backup.progress and broadcasts it to subscribed TCP/WS sessions. Pushed messages are raw event objects, not command responses, and include event: "backup.progress":

{
  "event": "backup.progress",
  "type": 3,
  "data": {
    "active": true,
    "run_id": "20260701-141500-000001",
    "type": "full",
    "trigger": "manual",
    "status": "running",
    "phase": "publish_remote",
    "message": "remote manifest publish backup-eu-1",
    "current_participant": "",
    "overall_percent": 96,
    "participants_total": 4,
    "participants_done": 4,
    "remote_total": 5,
    "remote_done": 4,
    "started_at": 1782915300,
    "updated_at": 1782915780,
    "finished_at": 0,
    "participants": []
  }
}

Notes

• StartFullBackup is synchronous, so the caller that starts the run may not receive its final response until the run has completed.
• Use a separate session, WebSocket connection, or another TCP client to poll GetBackupProgress or subscribe to backup.progress while the backup is running.
• If stream updates are not visible, first call GetBackupProgress from another session while the backup is running. If polling changes but the stream is silent, check that the session subscribed with chanels: ["backup.progress"] before the run started and that the client handles unsolicited event messages.
• The final done / 100% state is pushed through backup.progress; after that, polling returns phase: "idle" for successful runs.
• Remote publish progress is shown through phase: "publish_remote" and remote_total / remote_done.

Errors

HTTP Code	Description
403	Session does not have backup access