Use Iterator

Loop through arrays of records to perform actions on each item.

Iterator lets you loop through an array of records and perform actions on each one. It’s essential for workflows that need to process multiple records returned by Search Records or received via webhooks.

When to Use Iterator

Scenario	Example
Process search results	Send email to each person found
Handle webhook arrays	Create records for each item in order
Bulk updates	Update multiple records with calculated values
Notifications	Alert multiple people about an event

Understanding Iterator

Iterator expects an array as input. It then:

1. Takes the first item from the array
2. Runs all actions inside the Iterator with that item
3. Moves to the next item
4. Repeats until all items are processed

Selecting the array to loop over

Most array sources (Search Records, a webhook array field, a Bulk manual trigger) can be selected directly in the variable picker.

When a Code or Logic Function step returns a top-level array, its output appears in the variable picker as indexed entries (0, 1, 2, …). To loop over the array as a whole, select the Whole list option for that step — the Iterator then infers the shape of each item from the list automatically.

Basic Setup

Example: Email Everyone in Search Results

Goal: Find all contacts in a specific company and send each one a personalized email.

Step 1: Search for Records

1. Add Search Records action
2. Object: People
3. Filter: Company equals “Acme Inc”
4. This returns an array of people

Step 2: Check Results Exist

1. Add Filter action
2. Condition: {{searchRecords.length}} is greater than 0
3. This prevents Iterator errors on empty results

Step 3: Add Iterator

1. Add Iterator action
2. Array input: Select {{searchRecords}}
3. This creates a loop

Step 4: Add Actions Inside Iterator

Actions placed after Iterator run for each item:

1. Add Send Email action (inside Iterator)
2. To: {{iterator.currentItem.email}}
3. Subject: Hello {{iterator.currentItem.firstName}}!
4. Body: Personalized message using current item fields

Result

If Search Records returns 5 people, the Iterator:

• Sends email to person 1
• Sends email to person 2
• … continues for all 5

Accessing Current Item Data

Inside Iterator, use {{iterator.currentItem}} to access the current record:

Variable	Description
{{iterator.currentItem}}	The entire current record object
{{iterator.currentItem.id}}	Record ID
{{iterator.currentItem.email}}	Email field
{{iterator.currentItem.company.name}}	Related company name
{{iterator.index}}	Current position in array (0-based)

In the variable picker, you can either drill into a specific field of the current item, or pick Use the whole item to reference the entire current item ({{iterator.currentItem}}). Selecting the whole item is handy when you want to pass a full record straight into a downstream step rather than rebuilding it field by field.

Common Patterns

Update Multiple Records

Goal: Mark all overdue tasks as “Late”

1. Search Records (Tasks, Due Date < Today, Status ≠ Completed)
2. Filter (length > 0)
3. Iterator (searchRecords)
   └── Update Record
       - Object: Tasks
       - Record: {{iterator.currentItem.id}}
       - Status: Late

Create Records from Array

Goal: Webhook receives order with multiple items, create a record for each

1. Webhook Trigger (receives items array)
2. Filter (items.length > 0)
3. Iterator (trigger.body.items)
   └── Create Record
       - Object: Order Items
       - Name: {{iterator.currentItem.name}}
       - Quantity: {{iterator.currentItem.qty}}
       - Related Order: {{trigger.body.orderId}}

Conditional Processing Inside Loop

Goal: Only send email to contacts with valid emails

1. Search Records (People)
2. Iterator (searchRecords)
   └── Filter (currentItem.email is not empty)
       └── Send Email
           - To: {{iterator.currentItem.email}}

Troubleshooting

”Iterator expects an array”

Cause: You passed a single record instead of an array.

Fix: Make sure you’re passing the result of Search Records or an array field, not a single record.

✅ Correct: {{searchRecords}}
❌ Wrong: {{searchRecords[0]}}

Iterator Doesn’t Run

Cause: The array is empty.

Fix: Add a Filter before Iterator to check array length:

Filter: {{searchRecords.length}} > 0

Actions Run Too Many Times

Cause: Search Records returned more records than expected.

Fix:

• Add more specific filters to Search Records
• Set a limit on Search Records (max 200)
• Add Filter inside Iterator for additional conditions

Performance Considerations

• Credit usage: Each iteration consumes credits for its actions
• Time: Large arrays take longer to process
• Limits: Consider batching very large operations
• Rate limits: External API calls may hit rate limits with many iterations

Best Practices

1. Always check array length before Iterator to avoid errors
2. Add filters inside loops when not all items need processing
3. Rename your Iterator step to describe what it’s looping through
4. Test with small arrays before processing large datasets
5. Monitor workflow runs to ensure iterations complete as expected

Related

• Workflow Actions
• How to Use Branches
• Workflows FAQ