Process lists of records inside a workflow loop, control concurrency and rate limits per iteration, and collect aggregated results for downstream steps.
When You Need a Loop
Many automation scenarios involve collections of items rather than a single record. A nightly report might process every open support ticket. A data enrichment workflow might run an AI lookup for each contact in a CRM segment. A notification workflow might send a personalised message to every member of a project team. Without a loop, you would need to duplicate the same set of steps for each item — an approach that breaks the moment the collection size changes. Cotonity's Loop step solves this by wrapping a sub-workflow that executes once per item in a collection. The collection can be a static JSON array, a field in the incoming payload, or the output of a previous step such as an API fetch.
Configuring the Loop Step
Add a Loop step to your canvas and connect the data source — click the 'Collection' field and use the context picker to select an array from a previous step's output. Cotonity automatically detects array-type fields and marks them with a list icon in the picker for easy identification. Once the collection is set, a nested canvas opens inside the loop body where you build the per-item logic. Inside the loop, you reference the current item using the 'loop.item' context variable, and its index (zero-based) via 'loop.index'. For example, if your collection is an array of contact objects, 'loop.item.email' gives you the email address of the contact currently being processed. Steps inside the loop body can use all of Cotonity's standard step types: API calls, conditions, data transforms, and notifications.
Controlling Concurrency and Rate Limits
By default, Cotonity processes loop iterations sequentially — one item completes before the next begins. This is safe and predictable, but slow for large collections. If your downstream APIs support parallel requests, enable the 'Parallel execution' toggle and set a concurrency level (typically 5–20 concurrent iterations). Be cautious: running 50 parallel iterations against an API with a 60-requests-per-minute rate limit will immediately trigger throttling errors. Cotonity's built-in rate limiter can help — enable it on the Loop step and configure the maximum requests per second to ensure you stay within the target API's quota. See the article on rate limiting and throttling for detailed guidance on configuring this setting correctly.
Collecting Loop Outputs
After a loop completes, you often want to aggregate the results — for example, collecting all the enriched contact records into a new array to write to a spreadsheet. The Loop step automatically collects the output of the last step in each iteration into an array called 'loop.results'. Reference this array in steps after the loop closes to process the aggregated data. If an iteration fails and you have configured the loop to continue on error (rather than halt), that iteration's entry in 'loop.results' will contain an error object instead of a success payload, allowing downstream steps to filter and handle failed items separately. Use the Array Transform step after the loop to filter, map, or sort 'loop.results' before passing it to subsequent steps.