Skip to main content

getInvestigationFileUrl

You can use this method to check the status of a task started through the collectInvestigationPackage, startCommandExecutionOnEndpoint, or startRetrieveInvestigationFileFromEndpoint method. Once the task has been completed, you can also retrieve the download URL for the investigation package, log file, or investigation file uploaded in GravityZone using one of those methods.

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

Important

  • This method requires:

    • Advanced Investigation and Manage Networks rights.

    • A license that includes the EDR feature.

  • As an alternative to this method, you can download the investigation package, log file, or investigation file uploaded via collectInvestigationPackage, startCommandExecutionOnEndpoint, or startRetrieveInvestigationFileFromEndpoint 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, startRetrieveInvestigationFileFromEndpoint, or startCommandExecutionOnEndpoint.

Mandatory

String

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

activityId

The investigation activity ID returned by startRetrieveInvestigationFileFromEndpoint, collectInvestigationPackage, or startCommandExecutionOnEndpoint.

Mandatory

String

Must be the valid ID of a startRetrieveInvestigationFileFromEndpoint, collectInvestigationPackage, or startCommandExecutionOnEndpoint 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, startRetrieveInvestigationFileFromEndpoint, or startCommandExecutionOnEndpoint task. If the task completes with the status success, details about the file or package and its location in GravityZone centralized storage are also provided.

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. Therefore, perform the API call at regular intervals until status is success or failed.

Attribute

Type

Description

status

String

The current status of the collectInvestigationPackage, startCommandExecutionOnEndpoint, 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.

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

  • failed: The collection or upload failed.

  • success: The archive is available in the GravityZone 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 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 file or package could not be uploaded because its size exceeds the server's memory limit.

  • -112 or -311: Insufficient free 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, log file, or investigation 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: