For Loop Node

Use for_loop_node to repeat actions for each value in a list, or for each element matching a Playwright locator on the page—processing search results, downloading multiple files, or clicking through table rows. Exactly one of variable_name or locator is required.

Structure

Variable loop

{
  "type": "for_loop_node",
  "variable_name": "order_ids",
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_text(\"{order_ids[index]}\")",
          "prompt_instructions": "Click order {order_ids[index]}"
        }
      }
    }
  ],
  "reset_nodes": [],
  "on_error_in_loop": "raise"
}

Locator loop

{
  "type": "for_loop_node",
  "locator": "get_by_role(\"row\")",
  "index_variable_name": "row",
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "{locator[row]}.get_by_role(\"button\", name=\"Edit\")"
        }
      }
    }
  ],
  "reset_nodes": [],
  "on_error_in_loop": "raise"
}

At loop start the runtime waits up to locator_timeout for the first match to attach, then waits until the match count stays unchanged for 1 second (so slowly streaming rows are not missed), snapshots that count once, and iterates 0 .. count-1. An empty match set runs zero iterations with a warning (same as an empty list variable — the run does not fail).

Properties

Property	Type	Default	Description
`variable_name`	`str \| None`	`None`	Parameter list to iterate over. Mutually exclusive with `locator`
`locator`	`str \| None`	`None`	Playwright locator command whose matches are iterated. Mutually exclusive with `variable_name`
`index_variable_name`	`str`	`"index"`	Placeholder name used in `{var[<name>]}` / `{locator[<name>]}` and bare `{<name>}`
`locator_timeout`	`float`	`5.0`	Locator loops only: seconds to wait for the first match to attach; after that, count must stay stable for 1s before the loop starts
`max_iterations`	`int \| null`	`null`	Cap on iterations; extra items are skipped with a warning
`nodes`	`list[action_node \| for_loop_node \| if_else_node \| assert_locator_node]`	—	Actions for each iteration
`reset_nodes`	`list[action_node \| for_loop_node \| if_else_node \| assert_locator_node]`	`[]`	Actions to run after each iteration
`on_error_in_loop`	`"continue" \| "break" \| "raise"`	`"raise"`	Error handling behavior

The Index Variable

Variable loops

Inside a variable loop, {variable[index]} references the current iteration’s value. The token index comes from index_variable_name (default "index"):

order_ids = ["ORD-001", "ORD-002", "ORD-003"]

Iteration 1: {order_ids[index]} → "ORD-001"
Iteration 2: {order_ids[index]} → "ORD-002"
Iteration 3: {order_ids[index]} → "ORD-003"

Pattern	Expands to
`{order_ids[index]}`	Current list value
`{index_of(order_ids)}`	Current numeric index (`0`, `1`, …)
`{index}`	Current numeric index (same as `index_of`, using `index_variable_name`)

Locator loops

Locator loops use the same shape as variable loops: {locator[index]} is the current match (like {order_ids[index]}), and bare {index} is the numeric index:

locator = get_by_role("row")  (3 matches)

Iteration 1: {locator[index]} → get_by_role("row").nth(0)
Iteration 2: {locator[index]} → get_by_role("row").nth(1)
Iteration 3: {locator[index]} → get_by_role("row").nth(2)

With index_variable_name: "row":

Pattern	Expands to
`{locator[row]}`	Current match command (`<locator>.nth(<N>)`)
`{row}`	Current numeric index (`0`, `1`, …)
`{locator[row]}.get_by_role("button")`	Chained command on the current match

There is no {index_of(locator)} counterpart to {index_of(<variable>)}. It would carry no per-loop name, so in nested locator loops the outer loop would bind the inner loop’s occurrences. Use the bare {<index_variable_name>} form, which is scoped per level.

Using Multiple Variables in a Loop

You can iterate over multiple parameters in parallel by passing a comma-separated list to variable_name. Important: The first in variable_name is the main loop variable that controls:

How many iterations run (loop length)
Which index is used for each step

All additional names in the list are synced to the same index. In other words:

variable_name: "primary_var,secondary_var" → loop length comes from primary_var
{primary_var[index]} and {secondary_var[index]} both use the same index on each iteration

For each iteration, {variable[index]} is expanded for every name in the list:

{
  "type": "for_loop_node",
  "variable_name": "primary_var,secondary_var",
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "input_text": {
          "command": "get_by_role(\"textbox\", name=\"Primary Field\")",
          "input_text": "{primary_var[index]}"
        }
      }
    },
    {
      "type": "action_node",
      "interaction_action": {
        "input_text": {
          "command": "get_by_role(\"textbox\", name=\"Secondary Field\")",
          "input_text": "{secondary_var[index]}"
        }
      }
    }
  ]
}

If your parameters are:

primary_var = ["Value A1", "Value A2"]
secondary_var = ["Value B1", "Value B2"]

Then:

Iteration 1 uses {primary_var[index]} → "Value A1" and {secondary_var[index]} → "Value B1"
Iteration 2 uses {primary_var[index]} → "Value A2" and {secondary_var[index]} → "Value B2"

Waiting for Matches

Locator loops only. count() does not auto-wait, and the sleep after an action returns as soon as the page has loaded — which is immediately for an SPA that re-renders without navigating. Counting straight away would see zero rows and skip the loop body silently, so a locator loop:

Waits up to locator_timeout (default 5s) for the first match to attach
Then waits until the match count stays unchanged for 1 second, so rows that appear shortly after the first paint are included

Situation	Behavior
Matches appear and count stays stable for 1s	Loop runs over that stable count
No match within `locator_timeout`	Zero iterations, warning `No matching locator found`, run does not fail
Locator command doesn’t resolve (browser/page gone)	Raises, rather than silently looping zero times
More matches than `max_iterations`	Extra items skipped, logged as a warning

Raise locator_timeout for slow grids; set it to 0 to skip the first-match wait when rows are already on the page (the 1s stability wait still applies).

Storing One Value Per Iteration

output_variable_name is expanded like any other placeholder, so template it to give each iteration its own variable:

{
  "type": "action_node",
  "extraction_action": {
    "locator": {
      "command": "{locator[row]}.locator(\"td.PatientNameCell\")",
      "output_variable_name": "patient_{row}",
      "extraction_format": { "patient_{row}": "str" }
    }
  }
}

Without the placeholder every iteration overwrites the same variable and only the last row survives. Extracted values are appended to the task’s output data on every iteration either way — template the name only when you need to reference a specific row’s value later.

Nested Loops

for_loop_node can contain another for_loop_node. Give each loop a distinct index_variable_name so the outer index stays usable inside the inner loop:

{
  "type": "for_loop_node",
  "variable_name": "pages",
  "index_variable_name": "page_i",
  "nodes": [
    {
      "type": "for_loop_node",
      "variable_name": "items",
      "index_variable_name": "item_i",
      "nodes": [
        {
          "type": "action_node",
          "interaction_action": {
            "click_element": {
              "command": "get_by_text(\"{items[item_i]}\")",
              "prompt_instructions": "Page {page_i} ({pages[page_i]}), item {item_i} ({items[item_i]})"
            }
          }
        }
      ],
      "reset_nodes": [],
      "on_error_in_loop": "raise"
    }
  ],
  "reset_nodes": [],
  "on_error_in_loop": "raise"
}

Omitted `index_variable_name`?	Behavior
Both loops use default `"index"`	`{pages[index]}` and `{items[index]}` still work. Bare `{index}` in the inner body is bound by the outer loop. Prefer `{index_of(items)}` for the inner numeric index, or set distinct names.
Distinct names (`page_i`, `item_i`)	Outer and inner indexes can both be referenced clearly inside the innermost body.

The inner loop’s list must already exist when that loop starts (for example, extract items inside the outer iteration before the inner for_loop_node). An inner loop’s locator is itself expanded by the outer loop, so a locator loop can be scoped to the outer iteration — "locator": "{locator[row]}.locator(\"td\")" inside a loop over tr elements iterates that row’s cells. The inner count is taken from the already-scoped locator.

Data Sources

Loop variables can come from:

Source	When to Use
`input_parameters`	Known values before execution
`generated_parameters`	Values extracted during automation
`secure_parameters`	Sensitive values from secure storage

For dynamic iteration, extract values first:

[
  {
    "type": "action_node",
    "extraction_action": {
      "llm": {
        "extraction_format": { "item_ids": "List[str]" },
        "output_variable_names": ["item_ids"],
        "extraction_instructions": "Extract all item IDs"
      }
    }
  },
  {
    "type": "for_loop_node",
    "variable_name": "item_ids",
    "nodes": [ ... ]
  }
]

Reset Nodes

Actions that run after each iteration to return the browser to a known state. Essential for loops that navigate away from the starting page. Reset nodes also receive the current iteration’s placeholder bindings.

{
  "type": "for_loop_node",
  "variable_name": "documents",
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_text(\"{documents[index]}\")"
        }
      }
    }
  ],
  "reset_nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "close_tabs_until": {
          "matching_url": "https://example.com/documents"
        }
      }
    }
  ]
}

Reset Strategy Recommendations

Action	Reliability	Use When
`close_tabs_until`	High	Actions open new tabs
`go_to_url`	High	Navigate to known URL
`click_element` (navbar)	Medium	Persistent navigation exists
`go_back`	Low	Avoid—fails on errors

Avoid go_back for reset nodes. If an error occurs mid-loop, the browser may be on an unexpected page.

Error Handling

Behavior	Description
`"raise"`	Stop automation on error (default)
`"continue"`	Skip failed iteration, continue to next
`"break"`	Stop loop, continue with next node outside loop

{
  "type": "for_loop_node",
  "variable_name": "files",
  "on_error_in_loop": "continue",
  "nodes": [ ... ]
}

Use "continue" when some items may fail but you want to process as many as possible (e.g., downloading files where some may be missing).

Common Patterns

Click Every Matching Element

{
  "type": "for_loop_node",
  "locator": "get_by_role(\"checkbox\")",
  "nodes": [{
    "type": "action_node",
    "interaction_action": {
      "click_element": {
        "command": "{locator[index]}"
      }
    }
  }]
}

Download Multiple Files

{
  "type": "for_loop_node",
  "variable_name": "doc_links",
  "nodes": [{
    "type": "action_node",
    "interaction_action": {
      "click_element": {
        "command": "get_by_role(\"link\", name=\"{doc_links[index]}\")",
        "expect_download": true,
        "download_filename": "{doc_links[index]}.pdf"
      }
    }
  }]
}

Download One File Per Matched Row

When the rows are on the page but their identifiers aren’t known in advance, loop the locator and use the index for the filename. {row} works in any field, not just command:

{
  "type": "for_loop_node",
  "locator": "locator(\"tr.invoiceRow\")",
  "index_variable_name": "row",
  "on_error_in_loop": "continue",
  "nodes": [{
    "type": "action_node",
    "interaction_action": {
      "click_element": {
        "command": "{locator[row]}.get_by_role(\"link\", name=\"Download\")",
        "expect_download": true,
        "download_filename": "invoice_{row}.pdf",
        "prompt_instructions": "Download the invoice on row {row}"
      }
    }
  }]
}

Three matched rows download invoice_0.pdf, invoice_1.pdf, invoice_2.pdf. Keep the index in download_filename — a constant name makes every iteration overwrite the previous file.

Process Items and Return

{
  "type": "for_loop_node",
  "variable_name": "item_ids",
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "click_element": {
          "command": "get_by_text(\"{item_ids[index]}\")"
        }
      }
    },
    {
      "type": "action_node",
      "extraction_action": {
        "llm": {
          "extraction_format": { "details": "str" },
          "extraction_instructions": "Extract item details"
        }
      }
    }
  ],
  "reset_nodes": [{
    "type": "action_node",
    "interaction_action": {
      "go_to_url": { "url": "https://example.com/items" }
    }
  }]
}

Limitations

Variable loops require the list to be populated before loop execution
Locator loops wait for a stable count() (unchanged for 1s) once at start; DOM changes mid-loop do not change how many iterations run. Set max_iterations as a guard and re-check state inside the loop rather than relying on the initial count
Use {locator[index]} for the current match and bare {index} for the numeric index
When nesting locator loops, give each a distinct index_variable_name and reference {locator[row]} / {locator[cell]} so each level keeps its own match token
Locator loops that mutate the matched set (remove/add rows) should use reset_nodes and/or prefer extracting a stable list into a variable loop
Deep nesting is allowed; keep index_variable_name distinct per nesting level when you need both indexes

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

Structure

Variable loop

Locator loop

Properties

The Index Variable

Variable loops

Locator loops

Using Multiple Variables in a Loop

Waiting for Matches

Storing One Value Per Iteration

Nested Loops

Data Sources

Reset Nodes

Reset Strategy Recommendations

Error Handling

Common Patterns

Click Every Matching Element

Download Multiple Files

Download One File Per Matched Row

Process Items and Return

Limitations

​Structure

​Variable loop

​Locator loop

​Properties

​The Index Variable

​Variable loops

​Locator loops

​Using Multiple Variables in a Loop

​Waiting for Matches

​Storing One Value Per Iteration

​Nested Loops

​Data Sources

​Reset Nodes

​Reset Strategy Recommendations

​Error Handling

​Common Patterns

​Click Every Matching Element

​Download Multiple Files

​Download One File Per Matched Row

​Process Items and Return

​Limitations

Structure

Variable loop

Locator loop

Properties

The Index Variable

Variable loops

Locator loops

Using Multiple Variables in a Loop

Waiting for Matches

Storing One Value Per Iteration

Nested Loops

Data Sources

Reset Nodes

Reset Strategy Recommendations

Error Handling

Common Patterns

Click Every Matching Element

Download Multiple Files

Download One File Per Matched Row

Process Items and Return

Limitations