getLiveSearchQueryTaskResult

You can use this method to retrieve the results of a Live Search initiated via the runPredefinedLiveSearchQuery method.

API URL: CONTROL_CENTER_APIs_ACCESS_URL/v1.2/jsonrpc/incidents.

Important

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.
Results become available progressively as endpoints respond to the query task. The task may still be running when you call this method. Call the method periodically to retrieve newly available results until the expected number of results has been received or the task has completed.

Parameters

Parameter	Description	Included in request	Type	Value requirements
`companyId`	The ID of the managed company whose endpoints were queried and for which you want to retrieve the query results.	Optional	String	The string should consist of exactly 24 hexadecimal characters. By default, this parameter is the ID of the company associated with the API request.
`taskId`	The ID of the Run Live Search query task for which you want to view the results. This ID is returned by the `runPredefinedLiveSearchQuery` method. Tip This should be the ID of the parent task listed in the Tasks table in GravityZone Control Center, not the ID of an individual subtask.	Mandatory	String	The string should consist of exactly 24 hexadecimal characters. This parameter must reference a valid task that has available results and queried endpoints belonging to the specified company.

Parameter

Description

Included in request

Type

Value requirements

companyId

The ID of the managed company whose endpoints were queried and for which you want to retrieve the query results.

Optional

String

The string should consist of exactly 24 hexadecimal characters.

By default, this parameter is the ID of the company associated with the API request.

taskId

The ID of the Run Live Search query task for which you want to view the results. This ID is returned by the runPredefinedLiveSearchQuery method.

Tip

This should be the ID of the parent task listed in the Tasks table in GravityZone Control Center, not the ID of an individual subtask.

Mandatory

String

The string should consist of exactly 24 hexadecimal characters.

This parameter must reference a valid task that has available results and queried endpoints belonging to the specified company.

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": {...}
Under the `params` object
`page`	The results page number.	Optional	Integer	Default value: `1`. The minimum allowed value is `1`. Example "page": 2
`perPage`	The number of results displayed per page.	Optional	Integer	The upper limit is `100` items per page. The minimum allowed value is `1`. Default value: `30`. Example "perPage": 1

Return value

Attribute	Type	Description
`result`	Object	Live Search results organized by endpoint, along with pagination information: `total` (Integer): The number of result items available across all pages. `page` (Integer): The number of the page that is currently displayed. `perPage` (Integer): The maximum number of items returned per page. `pagesCount` (Integer): The total number of pages. `items` (Array of objects): The Live Search results for the current page. Each array item contains the results returned by a single endpoint. For details on the information included in each item, refer to `items`.

Objects

`items`

Each item provides the Live Search results returned by a single endpoint, along with metadata identifying the endpoint, the associated company, the task, and the result set.

Attribute	Type	Description
`_id`	String	The unique identifier of this result record.
`companyId`	String	The ID of the company that owns the queried endpoint.
`taskId`	String	The identifier of the Run Live Search query task that produced these results. Matches the `taskId` parameter from the request.
`protectedEntityId`	String	The ID of the endpoint that produced these results.
`results`	String	A JSON-encoded string containing the Live Search results for this endpoint. Tip Decode or parse the string to view the results in a human-readable JSON format. For example, you can use standard JSON parsers available in your programming language or online JSON formatting tools. You may need to remove escaping from the string before parsing it as JSON. Refer to `results` for a description of the fields contained in the resulting JSON object.

`results`

Contains information about the file or process returned by the Live Search query for a specific endpoint.

The properties included in this object depend on the query type initiated via the runPredefinedLiveSearchQuery method.

Attribute	Type	Description
`queryType` is `QUERY_RUNNING_HASH`
`hostname`	String	The hostname of the endpoint on which the file was found.
`path`	String	The absolute path of the file.
`queryType` is `QUERY_PROCESS_PER_HASH`
`pid`	Integer	The operating system-assigned process ID.
`parent`	Integer	The process ID of the parent process that created this process.
`path`	String	The full path to the executable file associated with the process.
`cmdline`	String	The full command line used to start the process, including any arguments and parameters.

Example

Request

{
    "jsonrpc": "2.0",
    "method": "getLiveSearchQueryTaskResult",
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "params": {
        "taskId": "67adcd628399ee12c90e6922",
        "companyId": "67a4a32929d8d9cc5a0987f2",
        "page": 1,
        "perPage": 30
    }
}

Response

Retrieving the results of a Live Search with queryType QUERY_RUNNING_HASH

{
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": {
        "total": 1,
        "page": 1,
        "perPage": 30,
        "pagesCount": 1,
        "items": [
            {
                "_id": "67adcd860538e3550aba779a",
                "companyId": "67a4a32929d8d9cc5a0987f2",
                "taskId": "67adcd628399ee12c90e6922",
                "protectedEntityId": "67adcd628399ee12c90e6922",
                "results": "{\"hostname\":\"cmurar-windows10\",\"path\":\"C:\\\\Windows\\\\System32\\\\svchost.exe\"}"
            }
        ]
    }
}

Retrieving the results of a Live Search with queryType QUERY_PROCESS_PER_HASH

{
    "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f",
    "jsonrpc": "2.0",
    "result": {
        "total": 1,
        "page": 1,
        "perPage": 30,
        "pagesCount": 1,
        "items": [
            {
                "_id": "6a2a76fc4c9c1be11363ff24",
                "protectedEntityId": "6a2a5dccdc4aea26f2cab111",
                "companyId": "67a4a32929d8d9cc5a0987f2",
                "taskId": "67adcd628399ee12c90e6922",
                "results": "{\"cmdline\":\"C:\\\\WINDOWS\\\\system32\\\\svchost.exe -k UnistackSvcGroup -s WpnUserService\",\"parent\":\"960\",\"path\":\"C:\\\\Windows\\\\System32\\\\svchost.exe\",\"pid\":\"716\"}"
            }
        ]
    }
}

In this section: