Loading

While

The while step runs its nested steps repeatedly as long as a Kibana Query Language (KQL) condition evaluates to true. The condition is re-evaluated at the end of every iteration.

Use while for polling patterns: checking a status until it reaches ready, retrying an operation until it succeeds, or waiting for an external job to complete. For iterating over a known collection, use foreach instead.

Schema convention. In each schema table on this page, the Location column indicates where each parameter sits in the YAML:

  • top level: Alongside type and name, at the top of the step or trigger definition.
  • `with`: Inside the step's with: block.
  • `on`: Inside the trigger's on: block.
Parameter Location Type Required Description
name top level string Yes Unique step identifier.
type top level string Yes Must be while.
condition top level string Yes KQL expression evaluated each iteration. The loop continues while it is true.
steps top level array Yes Loop body.
if top level string No KQL expression that skips the entire loop when it evaluates to false.
max-iterations top level number or object No Limit for number of iterations. Default is 2000. Bare number is treated as { limit: N, on-limit: continue }. Use the object form to opt into on-limit: fail.
timeout top level duration No Timeout for the entire loop.
on-failure top level object No Loop-level error-handling policy. Supports the same continue, retry, and fallback options as other steps.
iteration-timeout top level duration No Per-iteration timeout.
iteration-on-failure top level object No Per-iteration error-handling policy. Supports continue, retry, and fallback without failing the whole loop.
Warning

while defaults to max-iterations: 2000 with on-limit: continue, which means the step succeeds quietly when the cap is reached. If your loop needs to fail the workflow on hitting the cap, set on-limit: fail explicitly. Always think about the cap on loops that depend on external state to avoid runaway executions or silently truncated work.

Use loop-level guardrails to control the while step as a whole:

  • max-iterations caps the number of iterations to prevent runaway loops.
  • timeout limits the total time spent in the loop, across all iterations.
  • on-failure defines loop-level failure handling with the same continue, retry, and fallback options used by other steps.
  • if skips the entire loop when the condition evaluates to false.

Use iteration-level guardrails to control each pass through the loop:

  • iteration-timeout limits how long one iteration can run.
  • iteration-on-failure handles failures for one iteration with continue, retry, or fallback without failing the whole loop.
# Bare number: default `on-limit` is `continue` (the step succeeds when the limit is reached)
max-iterations: 60

# Object form: opt into `on-limit: fail` to fail the workflow when the limit is reached
max-iterations:
  limit: 60
  on-limit: fail

Inside the steps block of a while, the following variables are available:

Variable Contains
while.iteration Zero-based iteration counter. 
- name: poll_job
  type: while
  if: "inputs.poll : true"
  condition: "steps.check.output.status : pending"
  max-iterations:
    limit: 60
    on-limit: fail
  timeout: "10m"
  iteration-timeout: "30s"
  iteration-on-failure:
    retry:
      max-attempts: 2
      delay: "1s"
  steps:
    - name: check
      type: elasticsearch.search
      with:
        index: "jobs"
        query:
          term:
            id: "{{ inputs.job_id }}"
        size: 1

    - name: log_progress
      type: console
      with:
        message: "Attempt {{ while.iteration }}: status {{ steps.check.output.hits.hits[0]._source.status }}"

    - name: wait
      type: wait
      with:
        duration: "5s"

If the job hasn't left pending after 60 iterations (five minutes), the loop exits with failure.