Skip to main content

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:

  • 1 - Pending

  • 2 - In progress

  • 3 - Finished

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 BEST 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, the current status of the task for this specific endpoint. Possible values:

      Note

      This attribute is only visible if hasMoreSubtasks has the true value assigned.

      • 1 - Pending

      • 2 - In progress

      • 3 - Finished

    • endDate, the date and time when the stopped running on this endpoint.

  • totalTargetsCount - the total number of endpoints the task ran on.

Example

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 2024-03-15",
        "startDate": "2024-03-15T17:45:13",
        "status": 3,
        "type": 1,
        "owner": {
            "id": "65f17fcddb53ec33e302****",
            "userName": "[email protected]"
        },
        "company": {
            "id": "65f17fcddb53ec33e30****",
            "name": "Bitdefender"
        },
        "hasMoreSubtasks": false,
        "subtasks": [
            {
                "endpointId": "65f466d8c9dd23034805****",
                "endpointName": "Computer 10-L9OWIy",
                "endpointType": 262,
                "startDate": "2024-03-15T17:45:13",
                "status": 3,
                "endDate": "2024-03-15T17:55:12"
            },
            {
                "endpointId": "660c1d628bd2f47cae59****",
                "endpointName": "bdvm-virtual-machine",
                "endpointType": 262,
                "startDate": "2024-04-03T14:16:16",
                "status": 2,
                "endDate": "2024-04-03T14: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": "[email protected]"
        },
        "company": {
            "id": "21a295eeb1a43d8b497b23bb",
            "name": "Example"
        }
    }
}