collectInvestigationPackage

You can use this method to initiate a forensic collection task on an endpoint. The endpoint collects a predefined investigation package and uploads it to a centralized storage location in GravityZone for further analysis. For details on the data gathered as part of an investigation package, refer to ???.

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

Important

This method requires:
- A license that includes the EDR and Remote Shell features.
- Advanced Investigation and Manage Networks rights.
Only one investigation package collection task can be active on an endpoint at any given time. If a collection task is already pending or running, the API request fails.

Parameters

Parameter	Description	Included in request	Type	Value requirements
`targetId`	The ID of the managed endpoint targeted by the investigation package collection task.	Mandatory	String	The string should be a valid managed endpoint ID containing 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. Example "id": "ad12cb61-52b3-4209-a87a-93a8530d91cb"
`method`	The name of the method you are using to send the request.	Mandatory	String	Must be a valid method name. Example "method": "methodName"
`jsonrpc`	The version of JSON-RPC used by the request and the response.	Mandatory	String	The only possible value is `2.0`. Example "jsonrpc": "2.0"
`params`	An object containing the configuration of the request.	Mandatory	Object	No additional requirements. Example "params": {...}

Return value

Attribute	Type	Description
`result`	Object	Contains the identifier of the initiated task. Refer to `result`.

Objects

`result`

Attribute	Type	Description
`activityId`	String	The identifier of the initiated task. Tip Use this value as the `activityId` parameter in `getInvestigationFileUrl` to obtain the download URL for the forensic artifact archive after the task completes. You can also download the investigation package directly from GravityZone Control Center. Open the endpoint details from the Network section and go to the Investigation tab.

Example

Request:

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

Response:

{
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": {
        "activityId": "559bd17ab1a43d241b7b23d7"
    }
}

In this section: