runPredefinedLiveSearchQuery

You can use this method to initiate a Live Search across the specified endpoints. Depending on the query type, the search returns either:

files with the specified hash that are currently being executed, or
running processes associated with files that have the specified hash

Important

API URL: CONTROL_CENTER_APIs_ACCESS_URL/v1.2/jsonrpc/incidents.
To use this method, your license must include the Live Search feature.
This method requires the Live Search option to be enabled in the target endpoints' policy under the Live Search section.

Parameters

Parameter	Description	Included in request	Type	Value requirements
`queryType`	The type of predefined Live Search query to run.	Mandatory	String	Possible values: `QUERY_RUNNING_HASH`: The search returns files with the specified hash that are currently being executed. `QUERY_PROCESS_PER_HASH`: The search returns running processes associated with files that have the specified hash.
`querySpecifics`	The Live Search query parameters.	Mandatory	Object	This object cannot be empty. For information about its required properties, refer to `querySpecifics`.
`endpoints`	The endpoints on which the Live Search will be executed.	Optional	Array of strings	Each array element must be the valid ID of a managed endpoint within your company. If the array is empty or omitted, the query runs on all managed endpoints belonging to your company. The request fails if no managed endpoints are available.

Parameter

Description

Included in request

Type

Value requirements

queryType

The type of predefined Live Search query to run.

Mandatory

String

Possible values:

QUERY_RUNNING_HASH: The search returns files with the specified hash that are currently being executed.
QUERY_PROCESS_PER_HASH: The search returns running processes associated with files that have the specified hash.

querySpecifics

The Live Search query parameters.

Mandatory

Object

This object cannot be empty.

For information about its required properties, refer to querySpecifics.

endpoints

The endpoints on which the Live Search will be executed.

Optional

Array of strings

Each array element must be the valid ID of a managed endpoint within your company.

If the array is empty or omitted, the query runs on all managed endpoints belonging to your company. The request fails if no managed endpoints are available.

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": {...}

Objects

`querySpecifics`

Parameter	Description	Included in request	Type	Value requirements
`hash`	The hash that the returned files or processes must match.	Mandatory	String	Must be a valid SHA-256, MD5, or SHA-1 hash.

Return value

If the Live Search query is successfully initiated, the response includes the result (String) parameter, which contains the ID of the created task.

Warning

For the query to complete successfully, all prerequisites listed on the Live Search page must be met.

Tip

You can view the task generated for this search in GravityZone Control Center, in the Network > Tasks section.
To retrieve the detailed results of your Run Live Search query task, use the getLiveSearchQueryTaskResult method.

Example

Request:

{
    "jsonrpc": "2.0",
    "method": "runPredefinedLiveSearchQuery",
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "params": {
        "queryType": "QUERY_RUNNING_HASH",
        "querySpecifics": {
            "hash": "6e4640c14642129d6ffced03cc9eb455bd907aba819e742ddce708249c1b688f"
        },
        "endpoints": []
    }
}

Response:

{
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": "67adcd628399ee12c90e6922"
}

In this section: