Skip to main content

getInvestigationFileUrl

You can use this method to check the status of a task started through the collectInvestigationPackage or startRetrieveInvestigationFileFromEndpoint method and, once the task has completed, retrieve the download URL for the investigation file or investigation package uploaded in GravityZone using those methods.

API URL: CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/investigation.

Important

  • To use this method, your user account, your company, and the endpoint for which the file or package retrieval was previously initiated via collectInvestigationPackage or startRetrieveInvestigationFileFromEndpoint must satisfy all Remote Shell session prerequisites, except for the 2FA requirement.

  • As an alternative to this method, you can download the investigation file or package directly from GravityZone Control Center. Open the endpoint details from the Network section and go to the Investigation tab.

Parameters

Parameter

Description

Included in request

Type

Value requirements

targetId

The ID of the endpoint for which the file or package retrieval was previously initiated using collectInvestigationPackage or startRetrieveInvestigationFileFromEndpoint.

Mandatory

String

The string should be a valid managed endpoint ID containing exactly 24 hexadecimal characters.

activityId

The investigation activity ID returned by startRetrieveInvestigationFileFromEndpoint or collectInvestigationPackage.

Mandatory

String

Must be the valid ID of a startRetrieveInvestigationFileFromEndpoint or collectInvestigationPackage task previously initiated for the endpoint specified through targetId.

The string should contain exactly 24 hexadecimal characters.

General parameters

These are common parameters, available across all public API methods:

Parameter

Description

Included in request

Type

Value requirements

id

This parameter adds an identifier to the request, linking it to its corresponding response.

The target replies with the same value in the response, allowing easy call tracking.

Mandatory

String

No additional requirements.

method

The name of the method you are using to send the request.

Mandatory

String

Must be a valid method name.

jsonrpc

The version of JSON-RPC used by the request and the response.

Mandatory

String

The only possible value is 2.0.

params

An object containing the configuration of the request.

Mandatory

Object

No additional requirements.

Return value

Attribute

Type

Description

result

Object

The current status of the collectInvestigationPackage or startRetrieveInvestigationFileFromEndpoint task, along with details about the investigation file or package and its location in GravityZone centralized storage if the task completes successfully.

Refer to result for a detailed description of the parameters included in this object.

Objects

result

Tip

Result information is updated progressively as the endpoint executes the task. The task might still be running when this method is called, so continue calling it at regular intervals until status is success or failed.

Attribute

Type

Description

status

String

The current status of the collectInvestigationPackage or startRetrieveInvestigationFileFromEndpoint task.

Possible values:

  • pending: The task has been assigned to the endpoint but execution has not started yet.

  • in_progress: The file or package is currently being collected from the endpoint.

  • failed: The collection or upload failed.

  • success: The archive is available in the GravityZone centralized storage.

  • to_be_retrieved: The file has been collected from the endpoint but has not yet been uploaded to the centralized storage.

Important

The result object always contains this attribute. All other attributes are conditionally included based on the status value.

status is failed

errorCode

Integer

An error code describing the failure reason.

Possible values:

  • -99999: The task was canceled by the user.

  • -99998, -1002, -317, -20001, -1004, or -1005: The archive containing the investigation file or package could not be uploaded due to an internal server error.

  • -99997: The task exceeded the allowed execution time.

  • -1130 or -329: The archive containing the investigation file or package could not be uploaded because its size exceeds the server's memory limit.

  • -112 or -311: Insufficient disk space was available on the endpoint to complete the requested operation.

  • -1003 or -330: The proxy configuration was invalid.

    Tip

    If you encounter this error, verify the settings in the target endpoint's policy under General > Agent > Settings.

  • -161: Data collection could not initiate because the security agent on the target endpoint must be updated.

Tip

If any of these errors persist and no clear cause or resolution can be identified, contact Bitdefender Enterprise Support.

status is success

url

String

The full HTTPS URL of the archive containing the collected investigation file or package.

bucket

String

The storage bucket name.

fileId

String

The identifier of the file within the bucket.

Example

Request:

{
    "jsonrpc": "2.0",
    "method": "getInvestigationFileUrl",
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "params": {
        "targetId": "559bd17ab1a43d241b7b23c6",
        "activityId": "559bd17ab1a43d241b7b23c6"
    }
}

Response:

In this section: