Unwind Tasks
LAST UPDATED: JUNE 20, 2025
Understanding the Unwind Task
The Unwind task type can support various data processing scenarios. Common use cases include the following:
Allowing each item in an JSON array to be processed independently by downstream tasks.
Enabling conditional logic to evaluate each array element individually, allowing multiple branches to match rather than stopping at the first true condition.
Refer to this example for details.
Creating structured reports in which each array element produces a distinct row or entry (e.g., an Excel report)
If the Unwind task executes successfully, all downstream tasks will run n times, where n is the number of items deconstructed by the Unwind task.

The Stage and Stage 2 tasks executed 3 times as they are downstream of the Unwind task, which unwound three objects from an array.
Using the Unwind Task
There are two input parameters available for the Unwind task.
JSON Data: The JSON object to be processed. This can be a root-level array or an object that contains at least one array.
JSON Path of Array Field (Optional): The path to the specific array within the JSON object (provided in JSON Data) to be deconstructed.
.png?inst-v=e416ef0a-975f-4240-8b76-b2350608028d)
Specifying the JSON Data
The first step in using the Unwind task is to identify the JSON Data to deconstruct. The input value must contain at least one array. In the example below, the JSON Data parameter references the output from a task named Data, which returns an array at the root level.

This directs the Unwind task to deconstruct the root-level array, which contains two objects.
.png?inst-v=e416ef0a-975f-4240-8b76-b2350608028d)
In this example, since two objects were unwound, any downstream task—such as the Execute Twice Stage task—will execute or be suggested for execution twice, once per unwound item.

Specifying the Array Field to Deconstruct
In some scenarios, users may need to unwind an array nested within an object while retaining fields from the parent level. For example, an analyst might unwind an array of IP addresses while preserving contextual information—such as the triggering alert, its ID, priority, and timestamp—present at the root level.
ORIGINAL DATA STRUCTURE
The data structure in the example below illustrates a case where elements requiring individual processing (i.e., IP addresses) are stored in a nested array, while parent-level information must be retained across each iteration.
{
"alert_id": "evt-12345",
"priority": "high",
"source": "Firewall",
"timestamp": "2025-06-02T14:20:00Z",
"ip_addresses": [
"192.168.1.10",
"10.0.0.5",
"172.16.0.3"
]
}
POST-UNWIND DATA STRUCTURE
This structure can be generated by using the Unwind task and setting the JSON Path of Array Field to $.ip_addresses
, which deconstructs the array while preserving the surrounding context from the parent object.
[
{
"alert_id": "evt-12345",
"priority": "high",
"source": "Firewall",
"timestamp": "2025-06-02T14:20:00Z",
"ip_addresses": "192.168.1.10"
},
{
"alert_id": "evt-12345",
"priority": "high",
"source": "Firewall",
"timestamp": "2025-06-02T14:20:00Z",
"ip_addresses": "10.0.0.5"
},
{
"alert_id": "evt-12345",
"priority": "high",
"source": "Firewall",
"timestamp": "2025-06-02T14:20:00Z",
"ip_addresses": "172.16.0.3"
}
]
Walking Through the Process
To unwind the ip_addresses array while preserving root-level contextual information, configure the Unwind task as follows:

Specify the path to the JSON data that contains the array field to be deconstructed. This ensures that the fields at this level are preserved in the resulting data structure.
Provide the relative path to the array field to be deconstructed. In this case, use
$.ip_addresses
, which refers to the ip_addresses array located at the root of the object at the$.PlaybookData.Data.returnData
path.
RESULT
The Unwind task will not only create a separate object for each value unwound from the ip_addresses array but also retain all root-level fields returned by the path $.PlaybookData.Data.returnData
.

All root-level fields and their values are in the final data structure:
"alert_id": "evt-12345"
"priority": "high"
"source": "Firewall"
"timestamp": "2025-06-02T14:20:00Z"
Inspecting Downstream Task Executions
In the example above, downstream tasks executed or were suggested three times because the Unwind task deconstructed the ip_addresses array, which contained three items.
.png?inst-v=e416ef0a-975f-4240-8b76-b2350608028d)
Tasks downstream of an Unwind task execute once per unwound item, whether or not they take any input. For example, Stage tasks take no input but are still executed or suggested for execution n times when following an Unwind task, as each run follows a separate parallel path.

Users can view individual executions of downstream tasks as follows. In this example, the Output Data task displays each IP address that was unwound from the ip_addresses array (extracted from the Data task).

Click the task status icon of a downstream task.
In the top-right corner, click the {number} – {task status} dropdown.
Select a specific execution instance.
Recombining Execution Paths
The Merge task node can consolidate multiple execution paths created downstream of an Unwind task back into a single path.
WITHOUT MERGE TASK
Without a Merge task node, the Stage task runs once for each execution path, leading to multiple parallel execution paths.

WITH MERGE TASK
Including a Merge task node in the execution path consolidates the parallel branches created by the Unwind task before proceeding to the Stage task.

READER NOTE
For more information about the Merge task node, refer to this article.