Skip to main content
The Batch node collects events that arrive at the same point in a journey and releases them together as one aggregated payload. Use it to turn a burst of activity into a single notification (for example, “Your post received 17 likes”) instead of many. The first event into a batch owns the run and continues downstream when the batch releases. Later contributing events terminate at the Batch node, so the nodes after a batch run only once per batch.

​
When a Batch Releases

A batch releases as soon as any one of these is true:
  • Max items collected (max_items, default 100, up to 1000).
  • Wait period elapses with no new contributing event (a quiet, inactivity window).
  • Max wait period ceiling is reached, measured from the first event into the batch.
The wait period must be shorter than the max wait period: the quiet window releases an idle batch early, and the max wait period is the hard ceiling that always releases it.

​
Configuration

FieldDescription
Max itemsRelease the batch once this many events have collected. Defaults to 100 (1 to 1000).
Wait periodQuiet window. If no new event arrives within this span, the batch releases.
Max wait periodHard ceiling from the first event. The batch releases when this elapses, even if events are still arriving. Must be longer than the wait period.
Include event dataWhen on, the collected events are attached to the released payload. Configure which ones with Strategy and Count.
StrategyWhich collected events to retain: First, Last, Highest, or Lowest. Highest and Lowest require a sort key (a dot-path into the event, for example data.priority).
CountHow many events to retain (0 to 25). The tracked count still reflects the true total, even if fewer items are retained.
Category keyOptional partition key, a dot-path into the event (for example data.category). Events whose value at that path matches are batched together; different values are batched separately.
ConditionsOptional. Only run the node when the conditions evaluate true.
Journey batches are scoped per user (scope: user), so events are grouped by the recipient.

​
Batch Payload

When the batch releases, downstream nodes receive a batch object with the total count and the retained items: 
{
  "batch": {
    "count": 3,
    "items": [
      { "like_from": "Drew" },
      { "like_from": "Alex" },
      { "like_from": "Abby" }
    ]
  }
}
Reference this data in a send node’s template with variable syntax (for example, {{batch.count}}). When a Category key is set, events are grouped by category and each category is delivered under its own key: 
{
  "batch": {
    "likes":    { "count": 2, "items": [ { "like_from": "Drew" }, { "like_from": "Alex" } ] },
    "comments": { "count": 1, "items": [ { "comment": "Excellent post!" } ] }
  }
}

​
Via the API

In a journey definition, a Batch node uses type: "batch": 
{
  "type": "batch",
  "scope": "user",
  "wait_period": "PT1H",
  "max_wait_period": "P1D",
  "max_items": 100,
  "retain": { "type": "first", "count": 5 },
  "category_key": "data.category"
}
See Building Journeys via the API for the full node reference. Durations use ISO 8601 (for example, PT1H for one hour, P1D for one day).

​
What’s Next

Add to Digest

Aggregate events into a scheduled digest instead

Throttle

Rate-limit how often a point is reached

Send

Render the batch payload in a template

Building Journeys via the API

Full node reference and definitions