---
title: Aggregate event handler
description: The aggregate event handler allows you to aggregate alerts messages over a specified interval. This page includes aggregate options and usage examples.
url: https://docs.influxdata.com/kapacitor/v1/reference/event_handlers/aggregate/
estimated_tokens: 739
product: Kapacitor
version: v1
publisher: InfluxData
canonical: https://docs.influxdata.com/kapacitor/v1/reference/event_handlers/aggregate/
date: '2024-02-05T17:51:51+01:00'
lastmod: '2024-02-05T17:51:51+01:00'
---

The aggregate event handler aggregates multiple events into a single event.
It subscribes to a topic and aggregates published messages within a defined
interval into an aggregated topic.

## Options

The following aggregate event handler options can be set in a[handler file](/kapacitor/v1/reference/event_handlers/#create-a-topic-handler-with-a-handler-file).

|  Name  |  Type  |                                                 Description                                                 |
|--------|--------|-------------------------------------------------------------------------------------------------------------|
|interval|duration|                  How often to aggregate events. Interval must be specified in nanoseconds.                  |
| topic  | string |                             A topic into which to publish the aggregate events.                             |
|message | string |A template string where `{{.Interval}}` and `{{.Count}}` are available for constructing a meaningful message.|

### Example: handler file

```yaml
id: handler-id
topic: topic-name
kind: aggregate
options:
  interval: 300000000000
  topic: agg_5m
  message: '{{.Count}} new events in the last {{.Interval}}'
```

## Using the aggregate event handler

The aggregate event handler subscribes to a topic and aggregates messages
published to that topic at specified intervals.
The TICKscript below, `cpu_alert.tick`, publishes alerts to the `cpu` topic if
CPU idle usage is less than 10% (or CPU usage is greater than 90%).

#### cpu\_alert.tick

```js
stream
    |from()
      .measurement('cpu')
      .groupBy(*)
    |alert()
      .crit(lambda: "usage_idle" < 10)
      .topic('cpu')
```

Add and enable this TICKscript with the following:

```bash
kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert
```

Create a new handler file, `aggregated_cpu_alerts.yaml`, using the `aggregate`event handler that subscribes to the `cpu` topic, aggregates alerts from the
last 10 minutes, and publishes aggregated messages to a new `aggr_cpu` topic.*Handler files can be YAML or JSON.*

#### aggr\_cpu\_alerts.yaml

```yaml
id: aggr_cpu_alerts_10m
topic: cpu
kind: aggregate
options:
  interval: 600000000000
  topic: aggr_cpu
  message: '{{.Count}} CPU alerts in the last {{.Interval}}'
```

Add the handler file:

```bash
kapacitor define-topic-handler aggr_cpu_alerts_10m.yaml
```

Aggregated CPU alert messages will be published to the `aggr_cpu` topic every
10 minutes. Further handling of the aggregated events can be configured on the`aggr_cpu` topic.
| Name | Type | Description |
| --- | --- | --- |
| Name | Type | Description |
| interval | duration | How often to aggregate events. Interval must be specified in nanoseconds. |
| topic | string | A topic into which to publish the aggregate events. |
| message | string | A template string where  {{.Interval}}  and  {{.Count}}  are available for constructing a meaningful message. |