Core Plugins and tasks Loop
CertifiedExecute child tasks for each value in a list.
Core Plugins and tasks Loop
Execute child tasks for each value in a list.
Renders values (list, map, map, URI, or expression) and runs the child task group once per item.
The current item is available as item.value; item.index exposes the index; if the values was a map, the key is available as item.key.
It values was an internal storage URI, the loop will perform one iteration per line.
Control parallelism with concurrencyLimit (0 = unlimited, 1 = fully serialized, N = up to N concurrent task groups). To run tasks inside each group in parallel, wrap them in a Parallel task.
Each loop iteration will execute in an isolated context, to access any loop iteration task outputs outside of the loop, you need to define outputs.
type: io.kestra.plugin.core.flow.LoopExamples
The {{ item.value }} from the loop task is available to all tasks of the loop, even nested.
id: for_loop_example
namespace: company.team
tasks:
- id: loop
type: io.kestra.plugin.core.flow.Loop
values: ["value 1", "value 2", "value 3"]
tasks:
- id: before_if
type: io.kestra.plugin.core.debug.Return
format: "Before if {{ item.value }}"
- id: if
type: io.kestra.plugin.core.flow.If
condition: '{{ item.value == "value 2" }}'
then:
- id: after_if
type: io.kestra.plugin.core.debug.Return
format: "After if {{ item.value }}"
This flow uses YAML-style array for values. The task loop 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.Loop
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 {{ item.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.Loop
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 {{ item.value }}
- id: shell
type: io.kestra.plugin.scripts.shell.Commands
commands:
- sleep {{ item.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.Loop
values: "{{inputs.s3_buckets}}"
tasks:
- id: year
type: io.kestra.plugin.core.flow.Loop
values: "{{inputs.years}}"
tasks:
- id: month
type: io.kestra.plugin.core.flow.Loop
values: "{{inputs.months}}"
tasks:
- id: full_table_name
type: io.kestra.plugin.core.log.Log
message: |
Full table name: {{item.parents[1].value }}_{{item.parent.value}}_{{item.value}}
Direct/current loop (months): {{item.value}}
Value of loop one higher up (years): {{item.parents[0].value}}
Further up (table types): {{item.parents[1].value}}
Properties
tasks *array
1values *stringarray
The list of values for which Kestra will execute a group of tasks
Values can be defined as:
- A list of objects, individual objects will be coalesced to strings
- A string which will be deserialized as a JSON array
- An ION file URI, each line will be deserialized as an ION object then coalesced to a string
assets
Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.
io.kestra.core.models.assets.AssetsDeclaration
IGNOREFAILWARNAsset failure behavior
Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.
Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.
The assets consumed as inputs.
io.kestra.core.models.assets.AssetIdentifier
1The assets produced as outputs.
io.kestra.plugin.ee.assets.Dataset
1150{}1150io.kestra.plugin.ee.assets.File
1150{}1150io.kestra.plugin.ee.assets.Table
1150{}1150io.kestra.plugin.ee.assets.VM
1150{}1150io.kestra.core.models.assets.External
1150{}1150io.kestra.core.models.assets.Custom
11501Custom asset type
{}1150breakWhen string
A condition that determines whether the Loop should break its processing.
A Pebble expression evaluated after each loop iteration. The loop will break and stop processing new iteration only when the expression evaluates to a truthy value (true, a non-empty string, a non-zero number).
Special variables are available:
- item: the current iteration item variables
- iteration.executionId: the current iteration execution id
- iteration.state: the current iteration execution state
- iteration.outputs: the current iteration execution outputs
concurrencyLimit integer
1>= 0The number of concurrent task groups for each value in the values array
A concurrencyLimit of 0 means no limit — all task groups run in parallel.
A concurrencyLimit of 1 means full serialization — only one task group runs at a time, in order.
A concurrencyLimit greater than 1 allows up to the specified number of task groups to run in parallel.
errors array
List of tasks to run if any tasks failed on this FlowableTask.
fetchType string
AUTOAUTOFETCHSTORESpecifies how to fetch outputs from loop iterations
AUTO: check the values, if it comes from an internal storage URI, will resolves to STORE, otherwise, will resolved to FETCH FETCH: fetch outputs from loop iterations and make them directly accessible from the execution context STORE: store outputs in the internal storage from loop iterations
finally array
outputs array
Output values available and exposed outside the loop.
They can be fetched from the execution context using the outputs output of the loop task run.
io.kestra.core.models.flows.Output
^[a-zA-Z0-9][.a-zA-Z0-9_-]*1STRINGSELECTINTFLOATBOOLDATETIMEDATETIMEDURATIONFILEJSONIONURISECRETARRAYMULTISELECTYAMLEMAILFORMREUSABLE_INPUTStransmitFailed boolean
trueFlag specifying whether to fail the current task if any loop iteration fails or is killed.
