Playbook Executions

In ThreatConnect, you can use Playbooks to automate your cyberdefense tasks and custom processes. Once you design, activate, and execute a Playbook, it runs in real time and provides detailed logs of the execution. Details provided in the logs include the execution’s queued date, start date, completed date, and status.

Endpoint: /api/v3/playbook/executions

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields that may be included in responses returned from the /v3/playbook/executions endpoint, which is a read-only endpoint:

OPTIONS /v3/playbook/executions?show=readonly

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/playbook/executions endpoint:

OPTIONS /v3/playbook/executions/tql

Hint

See the “Retrieve Playbook Executions Completed During a Specific Time Range” and “Retrieve Executions for a Specific Playbook” sections for example use cases of the tql query parameter.

Schemas

Response Body

The default response returned from a successful GET request to the /v3/playbook/executions endpoint includes one or more objects with the following fields:

id: <Integer> The Playbook execution’s ID number.
playbookId: <Integer> The ID number of the Playbook that was executed.
playbookXid: <String> The XID of the Playbook that was executed.
completedTime: <DateTime> The date and time when the Playbook execution completed.
logLevel: <String> The log level used during the Playbook execution.
status: <String> The Playbook execution’s status.
queueTime: <DateTime> The date and time when the Playbook execution was queued.
startTime: <DateTime> The date and time when the Playbook execution started.

Example

{
    "id": <int>,
    "playbookId": <int>,
    "playbookXid": "<string>",
    "completedTime": "<datetime>",
    "logLevel": "<string>",
    "status": "<string>",
    "queueTime": "<datetime>",
    "startTime": "<datetime>"
}

Retrieve Playbook Executions

Retrieve All Playbook Executions

Send the following request to retrieve data for all Playbook executions in your Organization:

Request

GET /v3/playbook/executions

Response

{
    "data": [
        {
            "id": 95,
            "playbookId": 13122,
            "playbookXid": "GiTVUWaN",
            "completedTime": "2024-04-04T21:39:42Z",
            "logLevel": "DEBUG",
            "status": "Completed",
            "queueTime": "2024-04-04T21:39:31Z",
            "startTime": "2024-04-04T21:39:31Z"
        },
        {
            "id": 94,
            "playbookId": 14000,
            "playbookXid": "etUM6cLX",
            "logLevel": "TRACE",
            "status": "Failed",
            "queueTime": "2024-02-21T14:22:32Z",
            "startTime": "2024-02-21T14:22:32Z"
        },
        {...}
    ],
    "countFailure": 25,
    "status": "Success",
    "countSuccess": 70
}

Note

The countFailure and countSuccess fields provide the total number of failed and successful Playbook executions, respectively, included in the API response.

Retrieve Playbook Executions Completed During a Specific Time Range

The following request demonstrates how to use TQL to filter Playbook executions based on when they were completed. In the following example, the API request will retrieve data only for Playbook executions completed within the last hour:

Request (Decoded URL)

GET /v3/playbook/executions?tql=completedTime > "NOW() - 1 HOUR"

Request (Encoded URL)

GET /v3/playbook/executions?tql=completedTime%20%3E%20%22NOW()%20-%201%20HOUR%22

Retrieve Executions for a Specific Playbook

The following requests demonstrate how to use TQL to filter Playbook executions by the corresponding Playbook’s XID and ID number. For instructions on obtaining a Playbook’s XID and ID number, see Playbooks Overview.

Filter Executions by XID

In the following example, the API request will retrieve data only for executions of the Playbook whose XID is GiTVUWaN:

Request (Decoded URL)

GET /v3/playbook/executions?tql=playbookXid = "GiTVUWaN"

Request (Encoded URL)

GET /v3/playbook/executions?tql=playbookXid%20%3D%20%22GiTVUWaN%22

Filter Executions by ID Number

In the following example, the API request will retrieve data only for executions of the Playbook whose ID number is 12345:

Request (Decoded URL)

GET /v3/playbook/executions?tql=playbookId = 12345

Request (Encoded URL)

GET /v3/playbook/executions?tql=playbookId%20%3D%2012345