Batch

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

Field	Description
Max items	Release the batch once this many events have collected. Defaults to 100 (1 to 1000).
Wait period	Quiet window. If no new event arrives within this span, the batch releases.
Max wait period	Hard 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 data	When on, the collected events are attached to the released payload. Configure which ones with Strategy and Count.
Strategy	Which 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`).
Count	How many events to retain (0 to 25). The tracked `count` still reflects the true total, even if fewer items are retained.
Category key	Optional 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.
Conditions	Optional. 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).

Platform

Developer Tools

Help

When a Batch Releases

Configuration

Batch Payload

Via the API

​When a Batch Releases

​Configuration

​Batch Payload

​Via the API

When a Batch Releases

Configuration

Batch Payload

Via the API