Run Script

Cortex XDR REST API

post /public_api/v1/scripts/run_script

Initiate a new endpoint script execution action using a script from the script library. The script can be run on up to 1000 endpoints.

Required license: Cortex XDR Pro per Endpoint or Cortex XDR Pro per GB

Body parameters
request_dataObjectrequired

A dictionary containing the API request fields.

filtersArray

Array of filter fields for running the script on a number of endpoints at once.

fieldString (Enum)

String that identifies a list the filters match. Filters are based on the following keywords: - endpoint_id_list: List of endpoint IDs.

Allowed values:"endpoint_id_list"
operatorString (Enum)

String that identifies the comparison operator you want to use for this filter. Valid keywords and values are: in - endpoint_id_list: List of strings

Allowed values:"in"
valueArray[string]

Value that this filter must match.

script_uidString

GUID, unique identifier of the script, returned by the Get Scripts API per script.

parameters_valuesObjectrequired

Dictionary containing the parameter name, key, and its value for this execution, value.

You can obtain these values by running Get Script Metadata API.

xString
yInteger
timeoutInteger

Timeout in seconds for this execution. Default value is 600.

incident_idString

Incident ID. When included in the request, the Run Script action will appear in the Cortex XDR Incident View Timeline tab.

REQUEST BODY
{ "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "<endpoint ID>" ] } ], "script_uid": "<unique ID>", "parameters_values": { "x": "param input as returned in Get Script Metadata", "y": 4 } } }
CURL
curl -X 'POST'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
'https://api-yourfqdn/public_api/v1/scripts/run_script'
-d ''
Responses

Successful response

Body
replyObject

JSON object containing the query result.

action_idInteger

ID of the action initiated. ID will be used as a reference to track in the action center.

endpoints_countInteger

Number of endpoints the action was initiated on.

statusInteger

Integer representing whether the action: - 1: succeeded - 0: failed

RESPONSE
{ "reply": { "action_id": 22519813685366, "status": 1, "endpoints_count": 1 } }

Bad Request. Got an invalid JSON.

Body
err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"
err_extraString

Additional information describing the error.

RESPONSE
{ "err_code": "err_code_example", "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}", "err_extra": "err_extra_example" }

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body
err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"
err_extraString

Additional information describing the error.

RESPONSE
{ "err_code": "err_code_example", "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}", "err_extra": "err_extra_example" }

Unauthorized access. User does not have the required license type to run this API.

Body
err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"
err_extraString

Additional information describing the error.

RESPONSE
{ "err_code": "err_code_example", "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}", "err_extra": "err_extra_example" }

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body
err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"
err_extraString

Additional information describing the error.

RESPONSE
{ "err_code": "err_code_example", "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}", "err_extra": "err_extra_example" }

Internal server error. A unified status for API communication type errors.

Body
err_codeString

HTTP response code.

err_msgString

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"
err_extraString

Additional information describing the error.

RESPONSE
{ "err_code": "err_code_example", "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}", "err_extra": "err_extra_example" }