> ## 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.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Journey batch node

> Collect events at one point in a journey and release them as a single payload.

export const AppLink = ({href, children, name, bare}) => {
  const label = children || name || "Open in Courier";
  if (bare) {
    return <a href={href} target="_blank" rel="noreferrer">{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="app" href={href} target="_blank" rel="noreferrer">
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method" aria-hidden="true">↗</span>
    </a>;
};

export const Doc = ({href, children, name, bare}) => {
  const label = children || name || href;
  if (bare) {
    return <a href={href}>{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="doc" href={href}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">DOC</span>
    </a>;
};

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. 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 <Doc href="/docs/journeys/build">Building Journeys via the API</Doc> for the full node reference. Durations use ISO 8601 (for example, `PT1H` for one hour, `P1D` for one day).