AuthThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.AvailabilityPlannedWe plan to add this functionality in a future Elastic Stack update. Subject to changes.Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
Creates an action policy with a server-generated identifier. To create or replace an action policy with a client-supplied identifier, use PUT /api/alerting/v2/action_policies/{id}/.
descriptionstring · min length: 1 · max length: 1024
A description of the action policy. Absent when the policy has none; send null on PATCH to clear it.
destinationsuniononeOf[] · min items: 1 · max items: 10required
The list of destinations. At least one is required. Each one can appear at most once.
One of:
{}type: workflow
idstring · min length: 1 · max length: 150required
The workflow identifier.
typeenumrequired
The destination type.
Values:workflow
groupinguniononeOf
One of:(determined by mode)
mode: per_alert
one notification per alert lifecycle (default).
modeenumrequired
Values:per_alert
mode: all
a single notification for all matching alerts.
modeenumrequired
Values:all
mode: per_field
group by the specified fields.
modeenumrequired
Values:per_field
fieldsstring[] · min items: 1 · max items: 16required
The fields alerts are grouped by. At least one is required, and no other mode accepts them.
matcherobject
Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing tags. Set expression to a KQL query, which will be evaluated against each alert.
If you set both tags and expression, an alert must match the tags and the expression for the policy to apply. At least one of tags and expression must be set, so an empty matcher is rejected. Omit matcher entirely for a catch-all policy that applies to all alerts.
expressionstring · min length: 1 · max length: 4096
A KQL query that's evaluated against each alert. Supported fields are: alert_id, alert_status, group_hash, last_event_timestamp, severity, and your rule's query output columns under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression to match on tags alone.
tagsstring[] · min items: 1 · max items: 50
Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. An empty array is not accepted. Omit matcher.tags to match on matcher.expression alone.
namestring · min length: 1 · max length: 256required
The name of the action policy.
throttleuniononeOf
One of:(determined by strategy)
strategy: on_status_change
notify only on alert status transitions (default for per_alert).
strategyenumrequired
Values:on_status_change
strategy: per_status_interval
notify on transitions and at regular intervals.
strategyenumrequired
Values:per_status_interval
intervalstring · max length: 32required
The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.
strategy: time_interval
notify at regular intervals regardless of status (default for all/per_field).
strategyenumrequired
Values:time_interval
intervalstring · max length: 32required
The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.
created_atstring · format: date-time · max length: 64required
The ISO datetime when the action policy was created.
created_byobjectrequired
The actor who created the action policy.
profile_uidstringrequirednullable
User profile ID of the actor, or null when it cannot be resolved.
descriptionstring
A description of the action policy. Omitted when the policy has none.
destinationsuniononeOf[]required
The list of destinations.
One of:
{}type: workflow
idstring · min length: 1 · max length: 150required
The workflow identifier.
typeenumrequired
The destination type.
Values:workflow
enabledbooleanrequired
Whether the action policy is enabled.
groupinguniononeOf
One of:(determined by mode)
mode: per_alert
one notification per alert lifecycle (default).
modeenumrequired
Values:per_alert
mode: all
a single notification for all matching alerts.
modeenumrequired
Values:all
mode: per_field
group by the specified fields.
modeenumrequired
Values:per_field
fieldsstring[] · min items: 1 · max items: 16required
The fields alerts are grouped by. At least one is required, and no other mode accepts them.
idstringrequired
The unique identifier for the action policy.
matcherobject
Selects the alerts this policy applies to. Set tags to match alerts from rules with those routing tags. Set expression to a KQL query, which will be evaluated against each alert.
If you set both tags and expression, an alert must match the tags and the expression for the policy to apply. At least one of tags and expression must be set, so an empty matcher is rejected. Omit matcher entirely for a catch-all policy that applies to all alerts.
expressionstring · min length: 1 · max length: 4096
A KQL query that's evaluated against each alert. Supported fields are: alert_id, alert_status, group_hash, last_event_timestamp, severity, and your rule's query output columns under data.* (for example, data.host.name). Referencing other fields won't work. Omit matcher.expression to match on tags alone.
tagsstring[] · min items: 1 · max items: 50
Routing tags this policy should match. The policy applies to alerts from any rule whose metadata.routing_tags include at least one of these tags. An empty array is not accepted. Omit matcher.tags to match on matcher.expression alone.
namestringrequired
The name of the action policy.
snoozed_untilstring
The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.
throttleuniononeOf
One of:(determined by strategy)
strategy: on_status_change
notify only on alert status transitions (default for per_alert).
strategyenumrequired
Values:on_status_change
strategy: per_status_interval
notify on transitions and at regular intervals.
strategyenumrequired
Values:per_status_interval
intervalstring · max length: 32required
The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.
strategy: time_interval
notify at regular intervals regardless of status (default for all/per_field).
strategyenumrequired
Values:time_interval
intervalstring · max length: 32required
The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.
strategy: every_time
notify on every evaluation cycle (high volume).
strategyenumrequired
Values:every_time
updated_atstring · format: date-time · max length: 64required
The ISO datetime when the action policy was last updated.
updated_byobjectrequired
The actor who last updated the action policy.
profile_uidstringrequirednullable
User profile ID of the actor, or null when it cannot be resolved.
Indicates an invalid schema or parameters.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
errorstringrequired
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
messagestringrequired
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the request was not authenticated.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
errorstringrequired
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
messagestringrequired
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the user does not have the required privileges, or the current license does not support action policies. Creating, updating, upserting, and enabling action policies requires an active Enterprise license. Reading, disabling, snoozing, deleting, and rotating the API key of an existing policy do not, so existing policies can still be maintained after a license lapses.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
errorstringrequired
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
messagestringrequired
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates an unexpected server-side error.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
errorstringrequired
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
messagestringrequired
A readable explanation of the error. The wording can change without notice. Do not parse this field.
Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.
application/json
codestringrequired
Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
detailsmapstring to object
Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.
errorstringrequired
A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.
messagestringrequired
A readable explanation of the error. The wording can change without notice. Do not parse this field.