---
title: While
description: Reference for the while step, which loops while a KQL condition evaluates to true.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/workflows/steps/while
products:
  - Elastic Cloud Enterprise
  - Elastic Cloud Hosted
  - Elastic Cloud Serverless
  - Elastic Cloud on Kubernetes
  - Elastic Stack
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Planned
---

# 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`](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/workflows/steps/foreach) instead.

## Parameters


| 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.                                                                                                                                      |
| `max-iterations`       | top level | number or object | No       | Limit for number of iterations. Bare number is treated as `{ limit: N, on-limit: continue }`. Use the object form to opt into `on-limit: fail`. |
| `iteration-timeout`    | top level | duration         | No       | Per-iteration timeout.                                                                                                                          |
| `iteration-on-failure` | top level | object           | No       | Per-iteration error-handling policy. Same shape as `on-failure`.                                                                                |

<warning>
  `while` has no default `max-iterations`. Without an explicit cap, a `while` loop runs as long as its condition holds. Always set `max-iterations` on loops that depend on external state to avoid runaway executions.
</warning>


### `max-iterations` shape

```yaml
# Bare number: default `on-limit` is `continue` (the step succeeds when the cap is hit)
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
```


## Loop-local context

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

| Variable          | Contains                      |
|-------------------|-------------------------------|
| `while.iteration` | Zero-based iteration counter. |


## Example: Poll until a job finishes

```yaml
- name: poll_job
  type: while
  condition: "steps.check.output.status : pending"
  max-iterations:
    limit: 60
    on-limit: fail
  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.

## Related

- [Flow control steps](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/workflows/steps/flow-control-steps): Overview of all flow-control types.
- [Foreach step](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/workflows/steps/foreach): For iterating over a known array.
- [Loop break](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/workflows/steps/loop-break) and [Loop continue](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/explore-analyze/workflows/steps/loop-continue): Control loop flow from inside the body.