MCP Tools Reference: chronicle.googleapis.com

Tool: list_playbook_instances

Lists all execution instances of playbooks for a given case or alert.

Retrieves a historical list of all playbooks that have been run on a specific case and alert, showing their status and outcomes. This is useful for understanding what automated actions have already been taken, for auditing purposes, or for debugging playbook executions.

Workflow Integration: - Used to display the execution history of playbooks in a UI for an analyst to review. - Enables automated systems to verify if a certain playbook has already been executed on a case, preventing duplicate runs. - Provides crucial data for auditing security operations and for troubleshooting failing or unexpectedly behaving playbooks.

Use Cases: - A security analyst reviews the list of run playbooks on a case to get up to speed on the investigation. - A SOAR engineer checks the execution history of a playbook for a particular alert to diagnose a failure. - An automated rule queries the playbook instances to decide whether to escalate a case or run another playbook.

Args: project_id (str): Google Cloud project ID (required). customer_id (str): Chronicle customer ID (required). region (str): Chronicle region (e.g., "us", "europe") (required). case_id (int64): The identifier of the case for which to list playbook instances (required). alert_group_identifier (str): The alert group identifier to filter playbook instances. This is a unique string identifier associated with an alert, typically in the format 'Alert Rule Name_' (e.g., 'Virus Found..._'), not a simple numeric ID like '9'. This identifier must be retrieved from a specific alert.

Returns: A response object containing a list of playbook instance cards. Each card includes details such as the playbook's name, its execution status (e.g., 'COMPLETED', 'IN_PROGRESS', 'FAILED'), the playbook definition identifier, a description, and the run count. Returns an error message if the case or alert is not found or the request is invalid.

Example Usage: # List playbook instances for a specific alert group within a case list_playbook_instances(project_id='123', region='us', customer_id='abc', case_id=12345, alert_group_identifier='alert-group-xyz-789')

Next Steps (using MCP-enabled tools): - Use 'get_playbook_instance_details' to retrieve the full execution log and step-by-step results for a specific playbook run. - Use 'list_playbooks' to discover other playbooks that are available to be run.

The following sample demonstrate how to use curl to invoke the list_playbook_instances MCP tool.

Curl Request 
                  
curl --location 'https://chronicle.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_playbook_instances",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for ListPlaybookInstances.

ListPlaybookInstancesRequest

JSON representation 
{
  "projectId": string,
  "customerId": string,
  "region": string,
  "caseId": string,
  "alertGroupIdentifier": string
}
Fields
projectId

string

Project ID of the customer.
customerId

string

Customer ID of the customer.
region

string

Region of the customer.
caseId

string (int64 format)

Case ID for which to list playbook instances.
alertGroupIdentifier

string

Alert identifier to filter playbook instances.

Output Schema

LegacyPlaybookGetWorkflowInstancesCardsResponse is a response for getting workflow instances cards.

LegacyPlaybookGetWorkflowInstancesCardsResponse

JSON representation 
{
  "payload": [
    {
      object (ApiWorkflowInstanceCardDataModel)
    }
  ]
}
Fields
payload[]

object (ApiWorkflowInstanceCardDataModel)

Optional. The workflow instances cards.

ApiWorkflowInstanceCardDataModel

JSON representation 
{
  "status": enum (WorkflowInstanceStatusValue),
  "name": string,
  "definitionIdentifier": string,
  "description": string,
  "positionInQueue": integer,
  "runCount": string,
  "creationSource": enum (PlaybookCreationSourceEnum),

  // Union field _original_workflow_definition_identifier can be only one of the
  // following:
  "originalWorkflowDefinitionIdentifier": string
  // End of list of possible types for union field
  // _original_workflow_definition_identifier.

  // Union field _is_debug_mode can be only one of the following:
  "isDebugMode": boolean
  // End of list of possible types for union field _is_debug_mode.
}
Fields
status

enum (WorkflowInstanceStatusValue)

Required. Status is the status of the workflow instance.
name

string

Required. Name is the name of the workflow instance.
definitionIdentifier

string

Required. DefinitionIdentifier is the identifier of the workflow definition.
description

string

Optional. Description is the description of the workflow instance.
positionInQueue

integer

Required. PositionInQueue is the position of the workflow instance in the queue.
runCount

string (int64 format)

Required. RunCount is the number of times the workflow instance has been run.
creationSource

enum (PlaybookCreationSourceEnum)

Optional. CreationSource is the source of the workflow.

Union field _original_workflow_definition_identifier.

_original_workflow_definition_identifier can be only one of the following:
originalWorkflowDefinitionIdentifier

string

Optional. OriginalWorkflowDefinitionIdentifier is the original identifier of the workflow definition.

Union field _is_debug_mode.

_is_debug_mode can be only one of the following:
isDebugMode

boolean

Optional. IsDebugMode indicates if debug mode is enabled for the workflow instance.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌