Skip to main content
The Group action iterates over an array and executes a defined set of actions for each item in parallel. It’s perfect for processing lists of contacts, enriching multiple records, or performing batch operations—all items are processed simultaneously, not sequentially.

​
How it works

  1. You provide an array as input (e.g., a list of contacts, domains, or any collection)
  2. The Group node unpacks the array and runs its child actions for each item in parallel
  3. Each iteration has access to the current item via nodes.start
  4. Results are collected and returned as an array
Unlike a traditional loop, Group processes all items simultaneously. This makes it much faster but means you cannot depend on one item’s result to process another.

​
Configuration

PropertyDescription
ItemsThe array to iterate over. Use an expression like {{nodes.search.results}} or {{nodes.start.list}}
Fail on item failureIf enabled, the entire Group fails when any single item fails. If disabled, failed items return null and the Group continues.

​
Accessing data inside the Group

Inside the Group node, you have access to the current item and can reference parent data:

​
Current item

VariableDescriptionExample value
nodes.startThe current item being processed{ name: "Acme" }
nodes.start.fieldAccess a specific field on the item"acme.com"

​
Parent data with parentNodes

When you need to reference data from nodes outside the Group (parent context), use parentNodes: 
// Inside a Group - accessing parent data
const currentContact = nodes.start; // The current item
const companyName = parentNodes.enrich.company_name; // Data from outside the Group
const originalInput = parentNodes.start; // The original tool/play input
ExpressionDescription
nodes.startThe current item in the Group
parentNodes.{node_name}Access nodes outside the current Group
parentNodes.startAccess the original tool/play input
Use parentNodes when you need company-level data while processing contact-level items—like including the company name in a personalized email to each contact.

​
Common use cases

​
Company to contact workflows

The most common pattern is starting with company data and expanding to contact-level operations: Find and enrich stakeholders:
  1. Start → Receive company domain
  2. Find Contacts → Get list of contacts at the company
  3. Group → Iterates over contacts in parallel
    • Enrich Contact → Enrich {{nodes.start.email}}
    • Score Lead → Calculate fit score
    • Use parentNodes.enrich.company_name for company context
Push contacts to sales or campaigns:
  1. Start → Receive company with matched ICP
  2. Find Decision Makers → Get relevant stakeholders
  3. Group → Process each contact
    • Personalize Message → Generate outreach using parentNodes for company context
    • Add to Campaign → Enroll in sequence
    • Create CRM Contact → Push to HubSpot/Salesforce

​
Batch enrichment

Enrich multiple records from a search:
  1. Model Search → Returns array of companies
  2. Group → Processes all companies in parallel
    • Clearbit Enrich → Enriches {{nodes.start.domain}}
    • Model Custom Column → Saves enrichment data

​
Aggregate data from multiple sources

Fetch data from multiple APIs simultaneously:
  1. Variables → Define array of API endpoints
  2. Group → Calls all endpoints in parallel
    • HTTP Request → Calls {{nodes.start.url}}
  3. JavaScript → Combines all results

​
Output and results

The Group returns an array containing the output of the last node executed for each item. 
[
  { "enriched": true, "score": 85, "tier": "A" },
  { "enriched": true, "score": 62, "tier": "B" },
  null,
  { "enriched": true, "score": 91, "tier": "A" }
]
ScenarioResult
Item processed successfullyThe output of the last node in the Group
Item failednull (if “Fail on item failure” is disabled)
All items failedArray of null values
Access results in downstream nodes:
ExpressionReturns
{{nodes.group}}Full array of results
{{nodes.group[0]}}First item’s result
{{nodes.group.length}}Number of items processed
Replace group with the actual name of your Group node if you’ve renamed it.

​
Error handling

Control how the Group behaves when individual items fail:
SettingBehavior
Fail on item failure: OnEntire Group fails immediately when any item errors
Fail on item failure: OffGroup continues; failed items return null in results
Disable “Fail on item failure” when processing large batches where some failures are acceptable. Check for null values in results to identify and handle failed items downstream.

​
Rate limiting

Cargo automatically handles rate limits when calling external APIs within Groups. If an API returns a rate limit error, Cargo will:
  1. Pause the affected request
  2. Wait for the appropriate cooldown period
  3. Retry automatically
You don’t need to configure parallelism or add delays—rate limits are managed transparently.

​
Testing Groups

When testing a workflow that contains a Group, only a single test item is selected from the array—not all items. This allows you to verify your logic works correctly without processing the entire items.
During testing, the Group runs with one sample item to validate your workflow. In production, it processes all items in the array.

​
Best practices

Use a Filter or JavaScript action to remove unwanted items before the Group. Processing fewer items is always faster and cheaper than filtering inside the Group.
Minimize the number of actions inside a Group. If you need complex logic, consider creating a separate tool and calling it from within the Group.
When processing contacts for a company, use parentNodes to access company-level data like name, industry, or enrichment results.
When “Fail on item failure” is disabled, always check for null values in results. Use a JavaScript action to filter and handle failures appropriately.

​
Example: Stakeholder enrichment and outreach

A complete workflow that finds contacts at a company, enriches them, and adds to a campaign:
  1. Start — Receives { company_domain: "acme.com", company_name: "Acme Inc" }
  2. Find Contacts — Returns array of contacts at the company
  3. Group — Processes each contact in parallel
    • Enrich Contact — Enriches {{nodes.start.email}}
    • JavaScript — Builds personalized message using: 
      const contact = nodes.enrich;
const company = parentNodes.start.company_name;

return {
  subject: `${contact.first_name}, quick question about ${company}`,
  personalization: `I noticed you're the ${contact.title} at ${company}...`,
};
    • Add to Campaign — Enrolls contact with personalized content
  4. JavaScript — Summarizes results 
{
  "contacts_processed": 5,
  "enrolled_in_campaign": 4,
  "failed": 1
}

JavaScript

Transform data and process Group results with custom JavaScript.

Filter

Remove items from arrays before processing.

Branch

Handle empty arrays or check for errors after grouping.

Variables

Store intermediate results within loop iterations.