Execute a group of tasks for each value in the list.
You can control how many task groups are executed concurrently by setting the concurrencyLimit property.
- If you set the
concurrencyLimitproperty to0, Kestra will execute all task groups concurrently for all values. - If you set the
concurrencyLimitproperty to1, Kestra will execute each task group one after the other starting with the task group for the first value in the list.
Regardless of the concurrencyLimit property, the tasks will run one after the other — to run those in parallel, wrap them in a Parallel task as shown in the last example below (see the flow parallel_tasks_example).
The values should be defined as a JSON string or an array, e.g. a list of string values ["value1", "value2"] or a list of key-value pairs [{"key": "value1"}, {"key": "value2"}].
You can access the current iteration value using the variable {{ taskrun.value }} or {{ parent.taskrun.value }} if you are in a nested child task. You can access the batch or iteration number with {{ taskrun.iteration }}.
If you need to execute more than 2-5 tasks for each value, we recommend triggering a subflow for each value for better performance and modularity. Check the flow best practices documentation for more details.
type: "io.kestra.plugin.core.flow.ForEach"The {{ taskrun.value }} from the for_each task is available only to direct child tasks such as the before_if and the if tasks. To access the taskrun value of the parent task in a nested child task such as the after_if task, use {{ parent.taskrun.value }}.
id: for_loop_example
namespace: company.team
tasks:
- id: for_each
type: io.kestra.plugin.core.flow.ForEach
values: ["value 1", "value 2", "value 3"]
tasks:
- id: before_if
type: io.kestra.plugin.core.debug.Return
format: "Before if {{ taskrun.value }}"
- id: if
type: io.kestra.plugin.core.flow.If
condition: '{{ taskrun.value == "value 2" }}'
then:
- id: after_if
type: io.kestra.plugin.core.debug.Return
format: "After if {{ parent.taskrun.value }}"
This flow uses YAML-style array for values. The task for_each iterates over a list of values and executes the return child task for each value. The concurrencyLimit property is set to 2, so the return task will run concurrently for the first two values in the list at first. The return task will run for the next two values only after the task runs for the first two values have completed.
id: for_each_value
namespace: company.team
tasks:
- id: for_each
type: io.kestra.plugin.core.flow.ForEach
values:
- value 1
- value 2
- value 3
- value 4
concurrencyLimit: 2
tasks:
- id: return
type: io.kestra.plugin.core.debug.Return
format: "{{ task.id }} with value {{ taskrun.value }}"
This example shows how to run tasks in parallel for each value in the list. All child tasks of the parallel task will run in parallel. However, due to the concurrencyLimit property set to 2, only two parallel task groups will run at any given time.
id: parallel_tasks_example
namespace: company.team
tasks:
- id: for_each
type: io.kestra.plugin.core.flow.ForEach
values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
concurrencyLimit: 2
tasks:
- id: parallel
type: io.kestra.plugin.core.flow.Parallel
tasks:
- id: log
type: io.kestra.plugin.core.log.Log
message: Processing {{ parent.taskrun.value }}
- id: shell
type: io.kestra.plugin.scripts.shell.Commands
commands:
- sleep {{ parent.taskrun.value }}
This example demonstrates processing data across nested loops of S3 buckets, years, and months. It generates structured identifiers (e.g., bucket1_2025_March) by combining values from each loop level, while accessing parent loop values like years and buckets, which can be useful for partitioned storage paths or time-based datasets. The flow uses dynamic expressions referencing parent context.
id: loop_multiple_times
namespace: company.team
inputs:
- id: s3_buckets
type: ARRAY
itemType: STRING
defaults:
- bucket1
- bucket2
- id: years
type: ARRAY
itemType: INT
defaults:
- 2025
- 2026
- id: months
type: ARRAY
itemType: STRING
defaults:
- March
- April
tasks:
- id: buckets
type: io.kestra.plugin.core.flow.ForEach
values: "{{inputs.s3_buckets}}"
tasks:
- id: year
type: io.kestra.plugin.core.flow.ForEach
values: "{{inputs.years}}"
tasks:
- id: month
type: io.kestra.plugin.core.flow.ForEach
values: "{{inputs.months}}"
tasks:
- id: full_table_name
type: io.kestra.plugin.core.log.Log
message: |
Full table name: {{parents[1].taskrun.value }}_{{parent.taskrun.value}}_{{taskrun.value}}
Direct/current loop (months): {{taskrun.value}}
Value of loop one higher up (years): {{parents[0].taskrun.value}}
Further up (table types): {{parents[1].taskrun.value}}
The number of concurrent task groups for each value in the values array.
If you set the concurrencyLimit property to 0, Kestra will execute all task groups concurrently for all values (zero limits!).
If you set the concurrencyLimit property to 1, Kestra will execute each task group one after the other starting with the first value in the list (limit concurrency to one task group that can be actively running at any time).
The list of values for which Kestra will execute a group of tasks.
The values can be passed as a string, a list of strings, or a list of objects.