​
Enabling Loop

To enable looping for a step:

  1. Click the step’s options menu (⋮)
  2. Click Add Loop
  3. Enter a loop expression in the Loop Expression field that will determine how the step iterates

The loop expression determines what item will be processed in each iteration. The step will execute repeatedly, processing one item at a time until the loop expression returns a termination value.

​
Loop Expression

  • A JavaScript expression that returns the next item to process
  • Returns null, undefined, or false to terminate the loop
  • Has access to special variables:
    • index: Current iteration number (starts at 0)
    • item: Current value being processed

​
Loop Output

  • When loop is enabled, the step’s output becomes an array
  • Each array element contains the output from one iteration
  • Output array maintains the order of processing

​
Loop Expression Rules

Loop Expression
// CORRECT - Return one item at a time
const items = input.data_array;
return items[index];

// INCORRECT - Never return full array
return input.data_array; // Will cause infinite loop

// INCORRECT - Don't use boolean conditions
return index < items.length; // Will cause type errors

​
Accessing Output

When a step has looping enabled, its output becomes an array containing the results from each iteration. You need to handle this array structure differently than non-looped steps:

  • Each array element contains the complete output from one iteration
  • The array maintains the order of processing
  • You must use array methods like map() to access individual iteration results
  • Direct property access will fail since the output is now an array
ACCESS_LOOP_OUTPUT
// CORRECT - Handle array output from loop step
const results = MODEL_STEP.output.map((item) => item.message);

// INCORRECT - Direct access to loop step output
const result = MODEL_STEP.output.message; // Will fail

​
Loop Termination Rules

  • Loop stops when expression returns:
    • null
    • undefined
    • false
  • Array bounds automatically handle termination:
const items = input.array;
return items[index]; // Returns undefined when index >= length

​
Examples

Here are some practical examples demonstrating common loop patterns and use cases:

​
Parallel API Requests

Process multiple API endpoints simultaneously:

CODE_PREPARE_URLS
const urls = [
  'https://api1.example.com/data',
  'https://api2.example.com/data',
  'https://api3.example.com/data',
];
return { urls };
HTTP_REQUEST (with loop)
// Loop Expression:
return CODE_PREPARE_URLS.output.urls[index];

// Configuration:
{
  "type": "http_request",
  "key": "HTTP_REQUEST",
  "loop": "return CODE_PREPARE_URLS.output.urls[index]",
  "url": "{{item}}",
  "method": "GET",
  "headers": {
    "Accept": "application/json"
  }
}
CODE_PROCESS_RESULTS
const results = HTTP_REQUEST.output.map((response) => {
  return {
    status: response.status,
    data: response.body,
  };
});
return { processed_results: results };

​
File Batch Processing

Process multiple files with consistent logic:

Input
{
  "files": {
    "type": "file",
    "array": true,
    "name": "Documents to Process",
    "desc": "Upload multiple files for processing",
    "extract_contents": true
  }
}
MODEL_ANALYZE (with loop)
// Loop Expression:
return input.files[index];

// Configuration:
{
  "type": "model",
  "key": "MODEL_ANALYZE",
  "loop": "return input.files[index]",
  "provider": {
    "model": "openai",
    "provider": "text",
    "response_format": "json",
    "messages": [
      {
        "role": "system",
        "content": "Analyze document content and return JSON with key findings."
      },
      {
        "role": "user",
        "content": "Analyze this document: {{item:contents}}"
      }
    ]
  }
}
CODE_AGGREGATE_RESULTS
const analyses = MODEL_ANALYZE.output.map((result, idx) => {
  return {
    filename: input.files[idx].file_filename,
    analysis: result.message,
  };
});
return analyses;

​
Troubleshooting

Common issues that may arise when working with loops and how to resolve them:

​
Infinite Loops

Loop Expression
// PROBLEM:
return input.items; // Never terminates

// SOLUTION:
return input.items[index]; // Returns undefined to terminate

​
Output Type Mismatches

Loop Expression
// PROBLEM:
const result = MODEL_STEP.output.message; // Fails for loop output

// SOLUTION:
const results = MODEL_STEP.output.map((item) => item.message);

​
Remove Loop

To remove a loop from a step:

  1. Click the step’s options menu (⋮)
  2. Click Remove Loop

Was this page helpful?

Raise issue
OutputConditional