Execute a step multiple times over a list of objects

How does the Iteration Step work?

The Iteration Step executes the same step(s) over each entry within a list. The only prerequisite to using an Iteration Step is ensuring that your input values have already been formatted into a list object.

What is a list?

A list is a specific data type with elements separated by commas that begins with [ and ends with ] . For example:

A list of numbers:


A list of strings:

["sales", "marketing", "finance"]

A list of JSON objects:

    "link": "",
    "title": "OpenAI",
    "source": "OpenAI"
    "link": "",
    "title": "OpenAI",
    "source": "YouTube"
    "link": "",
    "title": "OpenAI",
    "source": "Wikipedia"

How do I generate a list?

Lists can be generated in multiple different ways, including through an LLM step, code step, Google Search or API step. It ultimately comes down to what works best for your use-case, and we've provide a few examples below to help.

Generating a list via an LLM Step

Because our LLM Steps allow you to adjust the prompt until you've achieved the desired outcome, it's a simple matter of specifying the list format within your prompt.

Let's walk through an example application that takes in a country name as input, and returns the top 5 cities in that country. We'll adjust the existing workflow to return those top 5 cities in a list format:

Generating a list via a Code Step

As our Code Step allows you to utilize both Javascript and Python, you can hard-code your return statement to match the desired list format, e.g.

return(["San Francisco", "New York City", "Miami"]);

Generating a list via a Google Search Step

Our Google Search Step allows you to select the specific formatting of your resulting search:

The resulting output of the Google Search Step will be formatted like so:

// Output of the Google Search Step with Links Only

What is the element and element index?

An element is the actual object/value (e.g. string, number, or object) in your list.

The element index is the position of the element within the list, starting with the first element at index 0.

How do I reference the element?

You can reference the element by clicking the pill step_x.element within your Iteration Step:

In the example above, the LLM step will run 3 times, and the {{step_1.element}] will be replaced with sales , marketing , and finance as such:

  • Give me 3 personas in the sales department

  • Give me 3 personas in the marketing department

  • Give me 3 personas in the finance department

Is the element index required?

The element index is optional, but it can be used to perform powerful logic.

For example, in the case of our SEO blog writer, we use the element_index to help us write our introductions. Because our goal is to have the writer only write to the first section of the blog, the element index is useful for only applying the step in that paragraph.

So, we add a Conditional Step with:

  • step_x.element_index == 0

which allows us to use a separate LLM Step with the introduction for the first section of the blog only.

What does the output look like?

The iteration step will also output a list.

The output of each iteration will be added to the list in the same order of the input.

How do I turn the list into text?

You can turn the array back into text with a simple Text step that uses Liquid:

// Replace step_x.output

{% for chunk in step_x.output %}
{% endfor %}


Let's return to our example from earlier in this page, where our existing application now returns a list of the top 5 cities in a given country.

We're going to take this one step further, and use an Iteration Step to cycle through each of the cities, and perform an Image Generation Step of what each looks like:

The resulting output will give you 5 distinct images, one for each of the unique cities returned by your original LLM.

Last updated