> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch

> Collect events that arrive at a point in a journey and release them together as a single aggregated payload, controlled by item count, a quiet window, or a maximum wait.

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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"`:

```json theme={null}
{
  "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](/platform/journeys/building-journeys-via-api) for the full node reference. Durations use ISO 8601 (for example, `PT1H` for one hour, `P1D` for one day).

## What's Next

<CardGroup cols={2}>
  <Card title="Add to Digest" href="/platform/journeys/nodes/digest" icon="layer-group">
    Aggregate events into a scheduled digest instead
  </Card>

  <Card title="Throttle" href="/platform/journeys/nodes/throttle" icon="gauge-high">
    Rate-limit how often a point is reached
  </Card>

  <Card title="Send" href="/platform/journeys/nodes/send" icon="paper-plane">
    Render the batch payload in a template
  </Card>

  <Card title="Building Journeys via the API" href="/platform/journeys/building-journeys-via-api" icon="code">
    Full node reference and definitions
  </Card>
</CardGroup>