getTaskStatus

This method retrieves information about the status of a given task identified using its ID.

Important

This method has been updated to version 1.1. For information applicable to version 1.0, refer to this section.

Parameters

Parameter	Type	Optional	Description
`taskId`	String	No	The ID of the task you want to retrieve the status of.
`options`	Object	Yes	Use this set of options that to control what information is included in the request. To use this parameter, `returnSubtasks` must be included in the request and must have the `true` value assigned.
`returnSubtasks`	Boolean	Yes	Determines if the response also includes information on individual subtasks. Tip When a task is created for multiple endpoints, a subtask is created for each individual endpoint.
`page`	Number	Yes	The results page number. Default value: `1`.
`perPage`	Number	Yes	Number of items per page to be returned. Possible values: `1` - `1000`. Default value: `30`.
`subtaskFilters`	Object	Yes	Determines information on which subtasks is included in the response. To use this parameter, `returnSubtasks` must be included in the request and must have the `true` value assigned.
`status`	Number	Yes	When included in the request, this field determines what subtasks are included in the request, based on their current status. Possible values: `0` - Pending `1` - Processing `2` - Stopped (Failed) `3` - Processed (Finished) `4` - Retrying `5` - Stopped by user `6` - Downloading Note These values are available only for version 1.1.
`endedAfter`	String	Yes	When used, the response only includes information on tasks that have ended after a specific date and time.
`endedBefore`	String	Yes	When used, the response only includes information on tasks that have ended before a specific date and time.

Return value

This method returns an Object containing information about the tasks. The returned object contains:

name, the name of the task.
startDate, the start date of the task.
status, the status of the task. Possible values:
- 1 - Pending
- 2 - In progress
- 3 - Finished
type, the type of the task. Possible values:
- 1 - Scan task.
- 7 - Reconfigure task
- 16 - Isolate task
- 17 - Restore from isolation task
- 9 - Remove quarantine task
- 18 - Remove quarantine exchange task
- 14 - Remove all quarantine task
- 15 - Remove all quarantine exchange task
- 10 - Restore quarantine task
- 19 - Restore quarantine exchange task
- 20 - Add quarantine task
owner, an Object containing the following information about the owner of the task:
- id, the id of the account that created the task.
- userName, the name assigned to the account that created the task.
company, the company where the task was performed. The object has the following fields:
- id, the ID of the company.
- name, the company name.
hasMoreSubtasks, a Boolean indicating if there are more pages containing information on subtasks.
subtasks, an Object containing information on subtasks:
Note
This attribute is only visible if hasMoreSubtasks has the true value assigned.
- endpointId, the ID of the endpoint where the task ran.
- endpointName, the name of the endpoint where the task ran.
- endpointType, the type of endpoint where the task ran. Possible values:
  - 265 - The endpoint has been imported from Amazon AWS (EC2).
  - 262 - The Bitdefender agent has been normally installed on this endpoint.
  - 260 - The endpoint has been imported from Active Directory.
- startDate, the date and time when the task started running on this endpoint.
  Note
  This attribute is only visible if hasMoreSubtasks has the true value assigned.
- status, an integer indicating the current status of the task for this specific endpoint. Possible values:
  - 0 - Pending
  - 1 - Processing
  - 2 - Stopped (Failed)
  - 3 - Processed (Finished)
  - 4 - Retrying
  - 5 - Stopped by user
  - 6 - Downloading
  Note
  This attribute is visible only if hasMoreSubtasks has the true value assigned.
  These values are available only for version 1.1.
- s3FileLocation - a string indicating the relative object key (<companyId>/<endpointId>/<filename>) of the uploaded archive in the customer S3 bucket.
  Returned only for completed troubleshooting log gathering tasks initiated via runGatherLogsTask using storageType: 3 when status is 3.
  For details, refer to the examples below and to runGatherLogsTask.
- endDate, the date and time when the stopped running on this endpoint.
- subTaskId, string, unique identifier of the child task. Present for every returned subtask.
- scanType, number, scan type identifier. Present only for scan tasks. Omitted for non-scan tasks.
  Possible values:
  - 257 - Quick Scan
  - 258 - Full Scan
  - 259 - Custom Scan
  - 260 - Network Scan
  - 517 - Memory Scan
  - 518 - Yara Scan
totalTargetsCount - the total number of endpoints the task ran on.

Note

While methods like runGatherLogsTask target a single endpoint, other task types (such as network scans) can target multiple endpoints under a single parent task.

For single-endpoint tasks (for example, runGatherLogsTask), use Example 1 with "returnSubtasks": true to check execution and retrieve details such as s3FileLocation.
For multi-endpoint tasks, use Example 2 to paginate through subtasks and filter by status or completion time.

Example 1 - Basic request

For log gathering tasks created using runGatherLogsTask with custom S3 storage (storageType: 3), set "returnSubtasks": true in the options parameter.

When the subtask status reaches 3 (Finished), the s3FileLocation property provides the archive's relative object key (<companyId>/<endpointId>/<filename>) within your configured S3 bucket.

Request

{
  "params": {
    "taskId": "6ac788334821a5c67403b232",
    "options": {
      "returnSubtasks": true
    }
  },
  "jsonrpc": "2.0",
  "method": "getTaskStatus",
  "id": "7d2864e9-c67b-48a2-9ba3-0a11d47e83c"
}

Response

{
      "id": "7d2864e9-c67b-48a2-9ba3-0a11d47e83c",
      "jsonrpc": "2.0",
      "result": {
          "name": "Gather Existing Logs 2026-10-08",
          "startDate": "2026-10-08T11:39:12",
          "status": 3,
          "type": 28,
          "owner": {
              "id": "6a3a824660761c7dc703c2a1",
              "userName": "user@example.com"
          },
          "company": {
              "id": "6a3a824660761c7dc703c222",
              "name": "Bitdefender"
          },
          "hasMoreSubtasks": false,
          "subtasks": [
              {
                  "subTaskId": "6a6a0cad638779f96c07020",
                  "endpointId": "6a70aa3f48c6aa0a644d690",
                  "endpointName": "ubuntu-test-vm",
                  "endpointType": 1,
                  "startDate": "2026-10-08T11:39:12",
                  "status": 3,
                  "endDate": "2026-10-08T11:42:05",
                  "s3FileLocation":
  "6a3a824660761c7dc703c222/6a70aa3f48c6aa0a644d690f/ST_ubuntu-test-vm_2026_10_08_11_39.tar.gz"
              }
          ],
          "totalTargetsCount": 1
      }
  }

Example 2 - Advanced request with subtasks and filters

Request

{
     "params": {
        "taskId" : "65f46d08c6d2865b32048ba3",
        "options": {
            "returnSubtasks": true,
            "page":5,
            "perPage": 1
        },
        "subtaskFilters": {
            "status": 3,
            "endedAfter": "2024-03-14T19:45:10",
            "endedBefore": "2024-03-16T19:45:00"
        }
     },
     "jsonrpc": "2.0",
     "method": "getTaskStatus",
     "id": "7d2864e9-c67b-48a2-9ba3-0a11d47e83c8"
}

Response

{
    "id": "7d2864e9-c67b-48a2-9ba3-0a11d47e83c8",
    "jsonrpc": "2.0",
    "result": {
        "name": "Quick Scan 2026-08-15",
        "startDate": "2026-08-15T17:45:13",
        "status": 3,
        "type": 1,
        "owner": {
            "id": "65f17fcddb53ec33e302****",
            "userName": "owner@example.email.com"
        },
        "company": {
            "id": "65f17fcddb53ec33e30****",
            "name": "Bitdefender"
        },
        "hasMoreSubtasks": false,
        "subtasks": [
            {
                "endpointId": "65f466d8c9dd23034805****",
                "endpointName": "Computer 10-L9OWIy",
                "endpointType": 262,
                "startDate": "2024-03-15T17:45:13",
                "status": 3,
                "taskId": "6a4f93e3cca158e0810050a0",
                "endDate": "2024-03-15T17:55:12",
                "subTaskId": "683ee75b6c9598ab03098f93",
                "scanType": 257
            },
            {
                "endpointId": "660c1d628bd2f47cae59****",
                "endpointName": "bdvm-virtual-machine",
                "endpointType": 262,
                "startDate": "2026-08-15T14:16:16",
                "status": 2,
                "subTaskId": "6a4f93e3cca158e0810050a0",
                "endDate": "2026-08-15T14:16:17",
                "errorCode": "1",
                "errorMessage": "Endpoint client has lost connection with Security Server [1]"
            }

        ],
        "totalTargetsCount": 5
    }
}

Version 1.0

Parameters

Parameter	Type	Optional	Description
`taskId`	String	No	The ID of the task you want to retrieve the status of.

Return value

This method returns an Object containing information about the tasks. The returned object contains:

name, the name of the task.
startDate, the start date of the task.
status, the status of the task. Possible values:
- 1 - Pending
- 2 - In progress
- 3 - Finished
type, the type of the task. Possible values: 1 - Scan task.
owner, an Object containing the following information about the owner of the task:
- id, the id of the account that created the task.
- userName, the name assigned to the account that created the task.
company, the company where the task was performed. The object has the following fields:
- id, the ID of the company.
- name, the company name.

Example

Request

{        
    "params": {
        "taskId": "21a295eeb1a43d8b497b23b7"
    },
    "jsonrpc": "2.0",
    "method": "getTaskStatus",
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f"
}

Response

 {
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": {
        "name": "task",
        "startDate": "2023-10-27T12:08:42",
        "status": 1,
        "type": 1,
        "owner": {
            "id": "21a295eeb1a43d8b497b23ba",
            "userName": "owner@example.email.com"
        },
        "company": {
            "id": "21a295eeb1a43d8b497b23bb",
            "name": "Example"
        }
    }
}

In this section:

getTaskStatus

Important

Parameters

Tip

Note

Return value

Note

Note

Note

Note

Example 1 - Basic request

Example 2 - Advanced request with subtasks and filters

Version 1.0

Parameters

Return value

Example

Search results