List action policies | Kibana Serverless API documentation

List action policies Experimental

GET /api/alerting/v2/action_policies

Spaces method and path for this operation:

get /s/{space_id}/api/alerting/v2/action_policies

Refer to Spaces for more information.

Get a paginated list of action policies with optional filtering and sorting.

[Required authorization] Route required privileges: read_alerting-v2-action-policies.

Query parameters

page integer

The page number to return. Defaults to 1.

Minimum value is 1, maximum value is 10000.
per_page integer

The number of action policies to return per page. Defaults to 20.

Minimum value is 1, maximum value is 100.
filter string

A KQL filter to apply to the action policies. Supported fields: id, name, description, enabled.

Maximum length is 4096.
search string

A text string to search across action policy fields.

Minimum length is 1, maximum length is 256.
sort_field string

The field to sort action policies by.

Values are name, created_at, or updated_at.
sort_order string

The sort direction.

Values are asc or desc.

Responses

200 application/json

Returns a paginated list of action policies.
Hide response attributes Show response attributes object
- items array[object] Required
  
  The list of action policies.
  
  Hide items attributes Show items attributes object
  
  created_at string(date-time) Required
  
  The ISO datetime when the action policy was created.
  
  created_by object Required
  
  The actor who created the action policy.
  
  Additional properties are NOT allowed.
  
  Hide created_by attribute Show created_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
  
  description string
  
  A description of the action policy. Omitted when the policy has none.
  
  destinations array[object] Required
  
  The list of destinations.
  
  Hide destinations attributes Show destinations attributes object
  
  An action policy destination configuration.
  
  id string Required
  
  The workflow identifier.
  
  Minimum length is 1, maximum length is 150.
  
  type string Required Discriminator
  
  The destination type.
  
  Value is workflow.
  
  enabled boolean Required
  
  Whether the action policy is enabled.
  
  grouping object
  
  One of:
  object object object
  
  How matched alerts are batched into notifications. Omitted when none is set, which groups per alert.
  
  Hide attributes Show attributes
  
  fields array[string] Required
  
  The fields alerts are grouped by. At least one is required, and no other mode accepts them.
  
  At least 1 but not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.
  
  mode string Required Discriminator
  
  Value is per_field.
  
  id string Required
  
  The unique identifier for the action policy.
  
  matcher object
  
  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.
  
  Additional properties are NOT allowed.
  
  Hide matcher attributes Show matcher attributes object
  
  expression string
  
  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.
  
  Minimum length is 1, maximum length is 4096.
  
  tags array[string]
  
  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.
  
  At least 1 but not more than 50 elements. Minimum length of each is 1, maximum length of each is 128.
  
  name string Required
  
  The name of the action policy.
  
  snoozed_until string
  
  The ISO datetime until which the policy is snoozed. Omitted when the policy is not snoozed.
  
  throttle object
  
  One of:
  object object object object
  
  The throttle configuration for notifications. Omitted when none is set.
  
  Hide attributes Show attributes
  
  interval string Required
  
  The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.
  
  Maximum length is 32.
  
  strategy string Required Discriminator
  
  Value is per_status_interval.
  
  The throttle configuration for notifications. Omitted when none is set.
  
  Hide attributes Show attributes
  
  interval string Required
  
  The throttle interval duration (e.g. 5m, 1h) that sets the notification cadence.
  
  Maximum length is 32.
  
  strategy string Required Discriminator
  
  Value is time_interval.
  
  updated_at string(date-time) Required
  
  The ISO datetime when the action policy was last updated.
  
  updated_by object Required
  
  The actor who last updated the action policy.
  
  Additional properties are NOT allowed.
  
  Hide updated_by attribute Show updated_by attribute object
  
  profile_uid string | null Required
  
  User profile ID of the actor, or null when it cannot be resolved.
- page number Required
  
  The current page number.
- per_page number Required
  
  The number of action policies per page.
- total number Required
  
  The number of action policies matching the query. This count is an estimate: results above 10,000 may be reported as 10,000.
400 application/json

Indicates an invalid schema or parameters.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
401 application/json

Indicates the request was not authenticated.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
403 application/json

Indicates the user does not have the required privileges to perform the request.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
500 application/json

Indicates an unexpected server-side error.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.
503 application/json

Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.
Hide response attributes Show response attributes object
- code string Required
  
  Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.
- details object
  
  Optional extra information about the error, for example field validation issues or the rule_id when that ID already exists.
  
  Additional properties are allowed.
- error string Required
  
  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.
- message string Required
  
  A readable explanation of the error. The wording can change without notice. Do not parse this field.

GET /api/alerting/v2/action_policies

curl \
 --request GET 'https://<KIBANA_URL>/api/alerting/v2/action_policies' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "items": [
    {
      "created_at": "2026-01-15T12:00:00.000Z",
      "created_by": {
        "profile_uid": "u_elastic_0"
      },
      "description": "Sends notifications for alerts generated by rules with the production tag.",
      "destinations": [
        {
          "id": "workflow-1",
          "type": "workflow"
        }
      ],
      "enabled": true,
      "grouping": {
        "mode": "per_alert"
      },
      "id": "action-policy-1",
      "matcher": {
        "tags": [
          "production"
        ]
      },
      "name": "Notify on production alerts",
      "throttle": {
        "strategy": "on_status_change"
      },
      "updated_at": "2026-01-15T12:00:00.000Z",
      "updated_by": {
        "profile_uid": "u_elastic_0"
      }
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1
}

Response examples (400)

{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "errors": [],
      "properties": {
        "page": {
          "errors": [
            "Too small: expected number to be >=1"
          ]
        }
      }
    }
  },
  "error": "Bad Request",
  "message": "page: Too small: expected number to be >=1"
}

Response examples (401)

{
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Authentication required to access this API."
}

Response examples (403)

{
  "code": "FORBIDDEN",
  "error": "Forbidden",
  "message": "The current user does not have the required privileges for this request."
}

Response examples (500)

{
  "code": "INTERNAL_SERVER_ERROR",
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}

Response examples (503)

{
  "code": "ALERTING_DISABLED",
  "error": "Service Unavailable",
  "message": "Alerting is disabled."
}