---
title: "Get background task state"
method: GET
path: "/v1/background-tasks/{task-id}"
tags: ["Background Tasks"]
---

# Get background task state

`GET /v1/background-tasks/{task-id}`

Retrieve the state and progress of a server-side background task started by another endpoint (for example, device configuration restore). Finished tasks remain available for a limited time after completion.

## Path parameters

- `task-id` integer, required

## Response `200`

Task state

- BackgroundTask
  - `id` integer — Task ID
  - `description` string — Human-readable task description
  - `state` 'pending' | 'running' | 'completed' | 'failed' — Current task state
  - `progress` integer — Completion percentage reported by the task
  - `completionTime` string, date-time, nullable — Time the task finished (null while pending or running)
  - `failureReason` string, nullable — Failure details (null unless state is failed)

## Other responses

- `401` — Unauthorized
- `404` — Task with given ID does not exist

## Changes

- **2026-09-15** `c87f37318fa9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/netxms/apis/netxms-api/changes/v1/background-tasks/:task-id/get.md)

---

[API](https://skmtc.dev/netxms/apis/netxms-api.md) · [All operations](https://skmtc.dev/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/netxms/apis/netxms-api/revisions/c87f37318fa9?raw)