Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

REST Run Playbook

Run a playbook against a container or check the playbook status.


Run a playbook against a container.




Run a playbook against a container.

Request parameters
You can use the REST API to run a playbook against a container.

Field Required Type Description
container_id required integer Id of the container to run the playbook on.
playbook_id required integer or string The name of the playbook in the form "/". Also can be the Id of the playbook to run.
scope optional list of integers or string Can be a string containing "all" or "new" or a list of integers containing artifact Ids. This allows the playbook to be run against a specific set of artifacts.
inputs optional JSON If specified, this value must be a JSON object with one or more key/value pairs, passed as an input for the child playbook that is called, specified by the "playbook_id" field. Be sure both of the following are true:
  • The child playbook that is called must be an input playbook, not an Automation playbook.
  • The inputs you provide must be valid for the child playbook.
run required Boolean true. Request the playbook to be run.

Example request
This is a request to run the playbook "file_analysis" against the container with id 42. You can infer that the "file_analysis" playbook is an input playbook by the presence of the "inputs" key in the request.

curl -k -u admin:changeme https://localhost/rest/playbook_run \
-d '{
	"container_id": 42,
	"playbook_id": "local/file_analysis",
	"scope": "new",
	"run": true,
	"inputs": {
            "file_hash": "09ca7e4eaa6e8ae9c7d261167129184883644d07dfba7cbfbc4c8a2e08360d5b",
            "file_name": "hello.txt"

Example response
A successful POST will return back an acknowledgement indicator and the ID of the newly created playbook run. Note that this API will only queue the playbook to run. The result indicates that the request is received, however the playbook may not successfully run (if there is a problem with the playbook, for example).

    "playbook_run_id": "1",
    "received": true


Check the status of a playbook run.




Check the status of a playbook run.

Example request
Get the status of playbook run Id 46.

curl -k -u admin:changeme https://localhost/rest/playbook_run/46 -G -X GET

Example response
A successful request returns a 200 response and a JSON object containing the status for the playbook.

	"action_exec": [],
	"cancelled": "",
	"container": 24,
	"id": 46,
	"last_artifact": 160,
	"log_level": 1,
	"message": "{\"message\":\"\",\"playbook_run_id\":46,\"result\":[{\"action\":\"whois ip\",\"app_runs\":[{\"action\":\"whois ip\",\"action_run_id\":46,\"app_message\":\"Registry: arin\\nASN: 8075\\nCountry: US\\nNets:\\nRange: -\\nAddress: One Microsoft Way\",\"app_name\":\"WHOIS\",\"app_run_id\":55,\"asset_name\":\"whois\",\"parameter\":\"{\\\"ip\\\": \\\"\\\"}\",\"per_parameter_status\":\"success\"}],\"close_time\":\"2016-01-15T22:15:58.05319+00:00\",\"create_time\":\"2016-01-15T22:15:55.252+00:00\",\"id\":46,\"message\":\"1 actions succeeded\",\"status\":\"success\",\"type\":\"investigate\"},{\"action\":\"whois domain\",\"app_runs\":[{\"action\":\"whois domain\",\"action_run_id\":47,\"app_message\":\"Organization: Amazon Technologies, Inc.\\nDomain: amazon.com\\nCity: Reno\\nName: Hostmaster, Amazon Legal Dept.\\nCountry: US\",\"app_name\":\"WHOIS\",\"app_run_id\":56,\"asset_name\":\"whois\",\"parameter\":\"{\\\"domain\\\": \\\"amazon.com\\\"}\",\"per_parameter_status\":\"success\"}],\"close_time\":\"2016-01-15T22:16:00.798179+00:00\",\"create_time\":\"2016-01-15T22:15:58.062+00:00\",\"id\":47,\"message\":\"1 actions succeeded\",\"status\":\"success\",\"type\":\"investigate\"}],\"status\":\"success\"}\n",
	"owner": 4,
	"playbook": 42,
	"start_time": "2016-01-15T22:15:55.171000Z",
	"status": "success",
	"test_mode": false,
	"update_time": "2016-01-15T22:16:00.813027Z",
	"version": 1

The return values follow:

Field Type Description
action_exec JSON For internal use.
cancelled String If the playbook was cancelled, this field will contain a message indicating why.
container Integer ID of the container used in this run.
id Integer ID of this playbook run.
last_artifact Integer For internal use.
log_level Integer Indicates if logging was enabled for this playbook run.
message String Message. The string value contains a JSON object with details about the results of the action run. NOTE: Contents and/or data type of this field is likely to change in the future.
owner Integer ID of the user who ran the playbook or null if there is no owner.
playbook Integer ID of the playbook used for this run.
start_time ISO 8601 formatted timestamp Timestamp (UTC) of when the playbook run was started.
status String Request the playbook to be run. One of the following:
  • failed
  • running
  • success
test_mode Boolean Request the playbook to be run.
update_time ISO 8601 formatted timestamp Timestamp (UTC) of when the playbook run was last active.
version Integer For internal use. Schema version.


Cancel a running playbook.

Example request
Cancel playbook run Id 46.

curl -k -u admin:changeme https://localhost/rest/playbook_run/46 \
-d '{
    "cancel": true

Example response
A successful POST will return a descriptive message and success indicator.

Success response body:
    "cancelled": true,
    "message": "<detail>"

Error response body:
    "failed": true,
    "message": "<reason>"
Last modified on 30 June, 2022
REST Run Action
REST Severity

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3

Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters