--- title: Action policy reference description: Grouping modes, throttle strategies, dispatch outcomes, and matcher field reference for {{alerting-v2}} action policies. url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5528/explore-analyze/alerting/kibana-alerting-v2/notifications/action-policy-reference-v2 products: - Kibana applies_to: - Elastic Cloud Serverless: Preview - Elastic Stack: Unavailable --- # Action policy reference Use this page when building action policies. Below, you will find details about valid matcher fields, grouping modes and frequency options, dispatch outcome, and more. For step-by-step guidance, refer to [Create and configure an action policy](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5528/explore-analyze/alerting/kibana-alerting-v2/notifications/create-configure-action-policy-v2). ## Matcher fields Use these fields in the **Matcher** expression to filter which episodes a policy applies to. Combine them with standard KQL operators, for example `data.severity: "critical" AND episode_status: "active"`. | Field | Description | Example | |------------------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | `episode_status` | Current lifecycle status of the episode. Accepted values: `active`, `inactive`, `pending`, `recovering`. | `episode_status: "active"` | | `data.*` | Dynamic payload fields sent by the rule. Available fields depend on the rule type and configuration. | `data.severity: "critical"` or `data.host.name: "web-01"` | | `rule.id` | Unique identifier for the rule that generated the episode. | `rule.id: "rule-001"` | | `rule.name` | Display name of the rule. | `rule.name: "High CPU"` | | `rule.labels` | Key-value labels attached to the rule. Use dot notation to target a specific label key. | `rule.labels.env: "production"` | ## Dispatch per options Controls how the policy batches matching episodes before sending a notification. | Option | Description | When to use | |---------|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | Episode | Each episode triggers its own notification independently. Default selection. | You need per-issue visibility and want to handle each problem separately. | | Group | The policy bundles episodes that share the same value for a specified `data.*` field into one notification per unique value. | A rule produces many related episodes (for example, one per service or host) and you want to reduce noise by grouping them. | | Digest | The policy combines all matching episodes into a single notification, regardless of what they have in common. | You want a single periodic summary of everything that matched, rather than individual alerts. | ## Throttle strategies Throttle strategies control how often the policy fires for a given episode or group. The available strategies depend on the **Dispatch per** setting. Not all strategies are valid for all modes. | Option | Description | When to use | |---------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | On status change | Notifies when the episode status changes (for example, active → recovering). One notification per transition. | You only need to know when something breaks and when it's resolved. No reminders needed. | | On status change + repeat at interval | Notifies on status change, then resends notifications at a regular interval while the episode remains in the same status. | You want status change alerts plus periodic notifications that a problem is still unresolved, in case it has been missed or pushed aside. | | At most once every… | Caps notifications at one per episode or group within the chosen interval, regardless of rule frequency. | You want to limit alert volume for noisy rules without missing new or ongoing issues. | | Every evaluation | Notifies on every rule evaluation. Can be noisy. Use sparingly and only with infrequent rule schedules. | You need a full audit trail of every evaluation, or the rule runs infrequently enough that noise isn't a concern. | ### Frequency options for Episode Available frequency options when you set **Dispatch per** to **Episode**. | Option | Description | Example | |---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | On status change | Notifies once when the episode opens and once when it recovers. No repeat notifications while it remains active. Best for when you trust your ticketing or incident workflow to track ongoing issues | A host goes down at 9:00am → one notification. Recovers at 11:00am → one notification. No notifications between them. | | On status change + repeat at interval | Same as On status change, but also sends a reminder at a set interval while the episode is still active. | A host goes down at 9:00am → notification. With a 1h repeat: reminder at 10:00am, 11:00am. Recovers at 11:30am → notification. | | Every evaluation | Fires on every rule evaluation, regardless of status. Can be noisy on frequent rule schedules. Avoid in production. | A rule running every 5 minutes with one active episode produces up to 288 notifications per day. | ### Frequency options for Group Available frequency options when you set **Dispatch per** to **Group**. | Option | Description | Example | |---------------------|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | At most once every… | Limits how often each group can notify, regardless of how many episodes match or how often the rule runs. | 10 episodes share `data.host.name: "web-01"`. With a 1h limit, you get at most one notification per hour for that group. | | Every evaluation | Fires on every rule evaluation for each unique group value. Still noisy on frequent rule schedules. | A rule running every 10 minutes with 5 unique host values produces up to 6 notifications per host per hour. | ### Frequency options for Digest Available frequency options when you set **Dispatch per** to **Digest**. | Option | Description | Example | |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| | Every evaluation | The only option for Digest. Fires on every rule run, bundling all matching episodes into one message. Pair with a longer rule schedule to avoid frequent summary messages. | A rule running every 30 minutes with 20 matching episodes produces one summary notification every 30 minutes containing all 20. | ## Dispatch outcomes The system records each notification attempt with one of the following outcomes. To investigate delivery issues, query the `.alert-actions` data stream in Discover and filter by the `outcome` field. | Outcome | What happened | |--------------|--------------------------------------------------------------------------------------------------------------------| | `dispatched` | The system sent the notification successfully. | | `throttled` | The system skipped delivery because the throttle interval hadn't elapsed. This is expected behavior, not an error. | | `suppressed` | Dispatch was blocked before the notification went out—the rule was acknowledged, snoozed, or deactivated. | | `unmatched` | No action policy matched this episode, so no workflow ran. | | `error` | An error occurred during processing. Check Kibana logs to identify the cause. |