Journey batch node

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 is between 1 minute and 1 day. The max wait period is at least the wait period and at most 7 days. The quiet window releases an idle batch early. 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. 1 minute to 1 day.
Max wait period	Hard ceiling from the first event. The batch releases when this elapses, even if events are still arriving. At least the wait period, up to 7 days.
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. First keeps the most recent events, newest first. Last keeps the earliest events, oldest first. 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. A field to group events by inside the batch, written as a reference such as `{{data.category}}`. Events still release together as one batch. See Categories.
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" }
    ]
  }
}

How you reference it depends on where:

Where	Write
Template text	`{{batch.count}}`
A loop over the items	`data.batch.items`

Template text resolves variables from data, so it leaves the root off. A loop’s expression runs against data, profile, and refs together, so it names data explicitly.

Categories

Set a category key to count and list events by a field’s value, for a digest such as “3 likes and 2 comments”. The batch still releases once, and the groups appear under batch.categories, keyed by each value:

{
  "batch": {
    "count": 5,
    "items": [
      { "type": "like", "from": "Drew" },
      { "type": "like", "from": "Alex" },
      { "type": "comment", "from": "Abby" }
    ],
    "categories": {
      "like": {
        "count": 3,
        "items": [{ "type": "like", "from": "Drew" }, { "type": "like", "from": "Alex" }]
      },
      "comment": {
        "count": 2,
        "items": [{ "type": "comment", "from": "Abby" }]
      }
    }
  }
}

Where	Write
Template text	`{{batch.categories.like.count}}`
A loop over the items	`data.batch.categories.like.items`

batch.count and batch.items always cover the whole batch. An event with no value at the category key counts in those totals but in no category, and categories is left out when no event had a value. retain is shared across categories. A count of 3 keeps 3 events for the whole batch, not 3 per category, so a category’s items can hold fewer events than its count, as comment does above.

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}}"
}

category_key must be one whole reference. A literal such as "data.category", or a reference inside other text, fails with category_key must be a reference like "{{data.category}}". See for the full node reference. Durations use ISO 8601 (for example, PT1H for one hour, P1D for one day).

Get started

Send messages

Journeys

Broadcasts

Design

In-app

Recipients

Tenants

Monitoring

Workspaces

Resources

Journey batch node

When a batch releases

Configuration

Batch payload

Categories

Via the API

​When a batch releases

​Configuration

​Batch payload

​Categories

​Via the API

When a batch releases

Configuration

Batch payload

Categories

Via the API