elastic · nastasha-solomon · May 21, 2026 · May 21, 2026
@@ -17,20 +17,25 @@ This page explains how action policies work. For creating and configuring them s
 ## What is an action policy [action-policies]
 
 
-An action policy is a saved object in your space that controls notification routing. It's not attached to a rule. It's global within the space, so when an episode is produced, the system evaluates all enabled policies in the space that are not snoozed and decides which ones apply.
+An action policy is a saved object in your space that controls notification routing. Policies can be **global** or **per-rule**:
+
+- **Global** policies apply to all episodes in the space, from any rule. When an episode is produced, the dispatcher evaluates all enabled global policies that are not snoozed. Global is the default type and suits most use cases.
+- **Per-rule** policies are scoped to a single rule. They apply only to episodes produced by that specific rule. Use a per-rule policy when routing is specific to one rule and you don't want it to affect other rules in the space. The rule association is set at creation and cannot be changed.
 
 Each policy has four controls:
 
 | Control | What it does |
 | --- | --- |
-| Match conditions (optional KQL) | Filters which episodes this policy applies to. An empty match condition matches all episodes in the space. |
-| Notify per (grouping) | Controls how episodes batch into notifications: one per episode, one per notification group (Notify per **Group**), or one digest for all. |
+| Match conditions (optional KQL) | Filters which episodes this policy applies to. An empty match condition matches all episodes covered by the policy's scope. |
+| Notify per | Controls how episodes batch into notifications: one per episode, one per notification group using **Group** mode, or one digest for all. |
 | Frequency | Controls how often the policy can notify for the same notification group. |
 | Destinations | One or more workflows to invoke when all conditions are met. |
 
 ## How policies apply to rules
 
-Action policies don't reference rules directly. You scope a policy using KQL over episode and rule fields, for example `rule.labels: "checkout"` or `data.severity: "critical"`. A policy applies to every matching episode in the space, from any rule.
+**Global policies** don't reference rules directly. You scope them using KQL over episode and rule fields, for example `rule.tags: "checkout"` or `data.severity: "critical"`. A global policy applies to every matching episode in the space, from any rule.
+
+**Per-rule policies** are bound to a specific rule at creation. They apply only to episodes from that rule, and you can still use match conditions to filter further within that rule's episodes.
 
 Multiple policies can match the same episode, and each runs independently. There's no precedence or merging between them. If no policy matches an episode, no notification is sent. This is intentional.
 
@@ -58,20 +63,20 @@ Each notification attempt results in one of the following outcomes.
 | --- | --- |
 | `dispatched` | A notification was sent. |
 | `throttled` | Dispatch was suppressed because the **frequency** interval had not elapsed. |
-| `suppressed` | The episode was suppressed before dispatch (acknowledged, snoozed, or deactivated). |
-| `unmatched` | No policy matched this episode; no workflow ran. |
+| `suppressed` | Dispatch was blocked before the notification went out. The episode was acknowledged, snoozed, or deactivated, or the space is currently in a maintenance window. |
+| `unmatched` | No policy matched this episode and no workflow ran. |
 | `error` | Processing failed. Check {{kib}} logs. |
 
 You can query these outcomes in Discover through the `.alert-actions` data stream.
 
 ## Why policies are separate from rules
 
-Rules don't own policies. A rule can't say "notify team X when it fires." Instead, team X creates an action policy that uses a KQL matcher to pick up matching episodes.
-
-This design means:
-- One policy can cover episodes from many rules.
+Policies are independent of rules, which means:
+- One global policy can cover episodes from many rules. For example, a policy matching `data.severity: "critical"` applies regardless of which rule produced the episode.
 - You can update routing without touching any rule.
-- Rules can be created without any notification policy, which is useful for testing.
+- Rules can be created without any action policy, which is useful for testing.
+
+When you do need routing that's specific to one rule, create a per-rule policy and bind it to that rule at creation.
 
 When you're ready to route notifications, go to [Create and configure an action policy](notifications/create-configure-action-policy.md).
 
@@ -23,6 +23,7 @@ Use these fields in the **Match conditions** expression to filter which episodes
 | `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.tags` | Tags attached to the rule. Use to match episodes from rules with a specific tag. | `rule.tags: "payment-service"` |
 | `rule.labels` | Key-value labels attached to the rule. Use dot notation to target a specific label key. | `rule.labels.env: "production"` |
 
 <!--[CONTENT NEEDED for M2: M2 adds two first-class episode-level severity fields that will be directly matchable in KQL:
@@ -42,7 +43,7 @@ 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 **notification group**). | A rule produces many related episodes (for example, one per service or host) and you want to reduce noise by batching them into shared notifications. |
+| Group | The policy bundles episodes that share the same value for a specified `data.*` field into one notification per unique value. Each unique value forms a **notification group**. | A rule produces many related episodes, such as one per service or host, and you want to reduce noise by batching them into shared notifications. |
 | 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. |
 
 ## Frequency [throttle-strategies]
@@ -51,7 +52,7 @@ Controls how the policy batches matching episodes before sending a notification.
 
 | 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 | Notifies when the episode status changes, for example from active to 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 notification 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. |
@@ -94,6 +95,6 @@ The system records each notification attempt with one of the following outcomes.
 |---|---|
 | `dispatched` | The system sent the notification successfully. |
 | `throttled` | The system skipped delivery because the **frequency** interval had not elapsed. This is expected behavior, not an error. |
-| `suppressed` | Dispatch was blocked before the notification went out—the rule was acknowledged, snoozed, or deactivated. |
+| `suppressed` | Dispatch was blocked before the notification went out. The episode was acknowledged, snoozed, or deactivated, or the space is currently in a [maintenance window](../../../alerts/maintenance-windows.md). |
 | `unmatched` | No action policy matched this episode, so no workflow ran. |
 | `error` | An error occurred during processing. Check {{kib}} logs to identify the cause. |
@@ -11,9 +11,9 @@ description: "Create action policies in the {{alerting-v2}}, configure match con
 # Create and configure an action policy [create-manage-action-policies]
 
 
-Action policies are part of the {{alerting-v2}} in {{kib}}. This page covers how to configure match conditions, set grouping and frequency, and attach workflow destinations. Where rules define what counts as a problem, action policies define what happens when one is detected — which episodes generate notifications, how they batch for dispatch, and where they're routed.
+Action policies are part of the {{alerting-v2}} in {{kib}}. This page covers how to configure policy type, match conditions, grouping, frequency, and workflow destinations. Where rules define what counts as a problem, action policies define what happens when one is detected: which episodes generate notifications, how they batch for dispatch, and where they're routed.
 
-Because policies are separate from rules and global within a space, you can update notification behavior across many rules at once without touching detection logic, and you can route the same alerts differently depending on severity or source. You create and manage policies from the **Action policies** page, not from the rule form.
+Because policies are separate from rules, you can update notification behavior across many rules at once without touching detection logic, and you can route the same alerts differently depending on severity or source. You create and manage policies from the **Action policies** page, not from the rule form.
 
 For match conditions fields, grouping modes, frequency options, and dispatch outcomes, refer to [Action policy reference](action-policy-reference.md).
 
@@ -25,12 +25,25 @@ For match conditions fields, grouping modes, frequency options, and dispatch out
 
 ## Policy fields [policy-fields]
 
+### Policy type [policy-type]
+
+An action policy can be **global** or **per-rule**:
+
+- **Global** policies apply to any episode in the space. Use a global policy when you want to route episodes from multiple rules. For example, a policy matching `rule.tags: "checkout"` applies to every rule with that tag.
+- **Per-rule** policies are scoped to a single rule. Use a per-rule policy when notification routing is specific to one rule and you don't want it to affect other rules in the space.
+
+The policy type is set at creation and cannot be changed. If you need a different type, create a new policy.
+
+### Tags [policy-tags]
+
+Optional string labels you assign to a policy to categorize it or filter it on the Action policies list. Unlike rule tags, policy tags describe the policy itself rather than the alerts it matches. You can add, edit, or remove tags at any time without affecting routing behavior.
+
 ### Match conditions [matcher]
 
 
-An optional KQL expression that filters which episodes this policy applies to. An empty match condition matches every episode in the space.
+An optional KQL expression that filters which episodes this policy applies to. An empty match condition matches every episode covered by the policy's scope. For a global policy, that means all episodes in the space. For a per-rule policy, it means all episodes from the associated rule.
 
-Use match conditions to route different episodes to different policies, for example, one policy for `data.severity: "critical"` episodes routed to PagerDuty and another for warnings routed to Slack. For available fields and examples, refer to [Match conditions fields](action-policy-reference.md#matcher-fields).
+Use match conditions to route different episodes to different policies, for example, one policy for `rule.tags: "payment-service"` episodes routed to PagerDuty and another for warnings routed to Slack. For available fields and examples, refer to [Match conditions fields](action-policy-reference.md#matcher-fields).
 
 <!--[CONTENT NEEDED for M2: The `data.severity: "critical"` example above will become the legacy approach once M2 ships. M2 promotes severity to `episode.severity` and `episode.severity_max` as first-class episode fields. Update this example to use `episode.severity: "CRITICAL"` and update the cross-reference to include the new fields. Also decide whether to retain `data.severity` as an alternative for rules that haven't migrated, or to remove it from guidance entirely.]
 -->
@@ -46,7 +59,7 @@ Use match conditions to route different episodes to different policies, for exam
 | Notify per | What it does | Available Frequency options |
 |---|---|---|
 | Episode | One notification per episode. | - On status change <br> - On status change + repeat at interval <br> - Every evaluation |
-| Group | Bundle episodes that share a field value. Specify **Group by** (for example `data.service.name` or `data.host.name`). | - At most once every… <br> - Every evaluation |
+| Group | Bundle episodes that share a field value. Specify a **Group by** field such as `data.service.name` or `data.host.name`. | - At most once every… <br> - Every evaluation |
 | Digest | One notification for all matching episodes combined. | Every evaluation |
 
 :::

@@ -5,21 +5,28 @@
   serverless: preview
 products:
   - id: kibana
-description: "Enable, disable, snooze, maintenance windows, bulk actions, and API key rotation for action policies in the {{alerting-v2}}."
+description: "View policy details, enable, disable, snooze, review execution history, and rotate API keys for action policies in the {{alerting-v2}}."
 ---
 
 # Manage action policies
 
-Action policies are part of the {{alerting-v2}} in {{kib}}. This page covers how to enable and disable policies, snooze them during planned outages, and rotate their API keys.
+Action policies are part of the {{alerting-v2}} in {{kib}}. This page covers how to view policy details, enable and disable policies, snooze them during planned outages, rotate their API keys, and review execution history.
 
-## Enable, snooze, and maintenance
+## View policy details
+
+From the **Action policies** list, you can open a policy to see its full configuration, including match conditions, grouping mode, frequency, and destinations. You can also edit, clone, delete, enable, disable, snooze, or update its API key without leaving the list page.
+
+## Execution history
+
+The dispatcher records the outcome of every notification attempt for each policy. To investigate delivery issues or audit which policies ran for an episode, query the `.alert-actions` data stream in Discover and filter by `outcome` or `policy_id`. For a description of each outcome, refer to [Dispatch outcomes](action-policy-reference.md#dispatch-outcomes).
+
+## Enable and snooze
 
 You can disable a policy so it is not evaluated for new episodes. You can snooze a policy for a defined window so that it does not dispatch notifications during that period. Policies that are not enabled or are snoozed are skipped when the dispatcher evaluates policies.
 
 ### Maintenance windows [maintenance-windows]
 
-
-Maintenance windows are scheduled periods during which a policy does not dispatch notifications. They are configured on the action policy alongside snooze and other policy controls, not on the rule. Rule evaluation continues and alert episodes can still be recorded in `.rule-events`. Only dispatch through that policy pauses. Use maintenance windows for planned deployments, infrastructure changes, or recurring quiet periods.
+During a [maintenance window](../../alerts/maintenance-windows.md), action policies stop dispatching notifications automatically. No policy configuration is required. Rule evaluation continues and alert episodes are still recorded in `.rule-events`. Maintenance windows are configured separately, not on the action policy.
 
 ## Update API keys