Splunk® Phantom (Legacy)

Python Playbook API Reference for Splunk Phantom

Splunk Phantom 4.10.7 is the final release of Splunk's Security Orchestration, Automation, and Response (SOAR) system to be called Splunk Phantom. All later versions are named Splunk SOAR (On-premises). For more information, see the Splunk SOAR (On-premises) documentation.

Session automation API

The Splunk Phantom Automation API allows security operations teams to develop detailed and precise automation strategies. Playbooks can serve many purposes, ranging from automating minimal investigative tasks that can speed up analysis to large-scale responses to a security breach. The following APIs are supported to leverage the capabilities of session automation using playbooks.


Use the build_phantom_rest_url API to combine the Splunk Phantom base URL and the specific resource path, such as /rest/artifact.

The build_phantom_rest_url API is supported from within a custom function.


This sample uses the phantom.build_phantom_rest_url API.

    Constructs a REST route given a list of part paths. Quotes each path part individually.
    Note that you must not pass in quoted endpoints, or they'll get re-quoted.

    >>> build_phantom_rest_url()

    >>> build_phantom_rest_url('container')

    >>> build_phantom_rest_url('container', 7)

    >>> build_phantom_rest_url('container', '7/')

    >>> build_phantom_rest_url('container/7/edit_options')

    >>> build_phantom_rest_url('decided_list', 'foo bar')

        *args (str|int): args to join together



Use the get_base_url API to retrieve the URL that points to your Splunk Phantom instance.

The get_base_url API is supported from within a custom function.


This sample uses the phantom.get_base_url() API.

import phantom.rules as phantom
import json

def on_start(container):
    url = phantom.get_base_url()

def on_finish(container, summary):

The return value is the base URL of the platform as configured in Administration > System Settings > Company Settings.

2016-02-13T01:29:25.977000+00:00: calling on_start(): on incident 'test', id: 107.
2016-02-13T01:29:26.020179+00:00: phantom.get_base_url(): called for playbook run '219'
2016-02-13T01:29:26.025000+00:00: No actions were executed
2016-02-13T01:29:26.034220+00:00: calling on_finish()
Playbook 'get_base_url (id: 175)' executed (playbook_run_id: 219) on incident 'test'(id: 107).
Playbook execution status is:'success'
	No actions were executed for this playbook and 'incident'
{"message":"No actions were executed","playbook_run_id":219,"result":[],"status":"success"}

 *** The Playbook has completed. Result: success ***


Use the get_phantom_home API to return the path to the Splunk Phantom home directory.

The get_phantom_home is supported from within a custom function.


The following examples show the return values for the get_phantom_home API on different types of installs.

On a release OVA or privileged install:

Thu Jan 03 2019 16:37:23 GMT-0800 (Pacific Standard Time): /opt/phantom

On an unprivileged install:

Thu Jan 03 2019 16:36:31 GMT-0800 (Pacific Standard Time): /home/username/directory_name


Use the get_rest_base_url API to return the base URL to the REST API of your Splunk Phantom instance. This API works on all Splunk Phantom instances, regardless of installation type, or the base URL found in the in Company Settings.

The get_rest_base_url is supported from within a custom function.


The following examples show the return values for the get_rest_base_url API on different types of installs.

On a release OVA or privileged install:

Thu Jan 03 2019 16:37:23 GMT-0800 (Pacific Standard Time):

On an unprivileged install, showing the custom HTTPS port:

Thu Jan 03 2019 16:36:31 GMT-0800 (Pacific Standard Time):


Use the requests API to interact with the Splunk Phantom platform through the REST API. By using phantom.requests instead of directly importing requests from site packages, you avoid the need to set the Splunk Phantom request headers by hand, meaning that you don't need to authenticate with the platform. For more information on how to use the requests package, see https://pypi.org/project/requests.

The requests API is supported from within a custom function.


This sample uses the phantom.requests() API.

def list_indicator_tags(indicator_id=None, **kwargs):
    List the tags on the indicator with the given ID
        indicator_id: The ID of the indicator to list the tags for
    Returns a JSON-serializable object that implements the configured data paths:
        tags: The tags associated with the given indicator
    ############################ Custom Code Goes Below This Line #################################
    import json
    import phantom.rules as phantom
    outputs = {}

    # Validate the input
    if indicator_id is None:
        raise ValueError('indicator_id is a required parameter')

    # phantom.build_phantom_rest_url will join positional arguments like you'd expect (with URL encoding)
    indicator_tag_url = phantom.build_phantom_rest_url('indicator', indicator_id, 'tags')

    # Using phantom.requests ensures the correct headers for authentication
    response = phantom.requests.get(
    phantom.debug("phantom returned status code {} with message {}".format(response.status_code, response.text))

    # Get the tags from the HTTP response
    indicator_tag_list = response.json()['tags']
    phantom.debug("the following tags were found on the indicator: {}".format(indicator_tag_list))
    outputs['tags'] = indicator_tag_list

    # Return a JSON-serializable object
    assert json.dumps(outputs)  # Will raise an exception if the :outputs: object is not JSON-serializable
    return outputs


Use set_action_limit in your playbook's on_start() block to set the maximum number of action calls that can be executed. The default is 50 action calls per container per Playbook. Each phantom.act() call can still result in multiple actions performed, resulting in more actions than this setting.

set_action_limit is not supported from within a custom function.

Last modified on 03 May, 2022
Data access automation API   Vault automation API

This documentation applies to the following versions of Splunk® Phantom (Legacy): 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7

Was this topic useful?

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