List rules Experimental

GET /api/alerting/v2/rules
Api key auth

Spaces method and path for this operation:

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

Refer to Spaces for more information.

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

Query parameters

  • page integer

    The page number to return. Defaults to 1. page * per_page cannot exceed 10000.

    Minimum value is 1, maximum value is 10000.

  • per_page integer

    The number of rules to return per page. Defaults to 20.

    Minimum value is 1, maximum value is 100.

  • filter string

    The filter to apply to the rules.

    Maximum length is 4096.

  • sort_field string

    The field to sort rules by.

    Values are kind, enabled, or name.

  • sort_order string

    The direction to sort rules.

    Values are asc or desc.

Responses

  • 200 application/json

    Returns a paginated list of rules.

    Hide response attributes Show response attributes object
    • items array[object] Required

      The list of rules.

      Hide items attributes Show items attributes object
      • artifacts array[object]

        Optional objects attached to the rule, such as a runbook or a dashboard. Each item has id, type, and data. The shape of data depends on type. For example, a runbook uses content and a dashboard uses dashboard_id. Known types are validated against that shape. Unknown types are stored when id, type, and data are present.

        Not more than 100 elements.

        Hide artifacts attributes Show artifacts attributes object
        • data object Required

          Structured artifact data.

          Additional properties are allowed.

        • id string Required

          Artifact identifier.

          Minimum length is 1, maximum length is 150.

        • type string Required

          Artifact type.

          Minimum length is 1, maximum length is 128.

      • created_at string(date-time) Required

        ISO timestamp when the rule was created.

        Format should match the following pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$.

      • created_by object Required

        Actor who created the rule.

        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.

      • enabled boolean Required

        Whether the rule is enabled.

      • grouping object

        Grouping configuration.

        Additional properties are NOT allowed.

        Hide grouping attribute Show grouping attribute object
        • fields array[string] Required

          Fields to group alerts by, e.g. ["host.name", "service.name"]. Should match ES|QL GROUP BY fields.

          Not more than 16 elements. Minimum length of each is 1, maximum length of each is 256.

      • id string Required

        Unique rule identifier.

      • kind string Required

        Whether the rule creates alerts (alert) or only stores matching events (signal).

        Any of:
        string-1 string string-2 string

        Creates an alert for each matching group and tracks it until it recovers. Use this when you want to detect a problem and notify or automate a response.

        Value is alert.

        Stores each match as a rule event you can query. Alerts are not created and notifications are not sent.

        Value is signal.

      • metadata object Required

        Rule metadata.

        Additional properties are NOT allowed.

        Hide metadata attributes Show metadata attributes object
        • builder_type string

          Identifies the rule builder that authored this rule (e.g. "threshold"). Absent for rules authored directly in ES|QL.

          Maximum length is 64.

        • description string

          Human-readable description of the rule.

          Maximum length is 1024.

        • name string Required

          Rule name (must be unique within the space).

          Minimum length is 1, maximum length is 256.

        • routing_tags array[string]

          Routing tags that link alerts from this rule to action policies. An action policy applies when its matcher.tags contains at least one of these tags. Only allowed when kind is "alert".

          At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.

        • tags array[string]

          Tags for categorization, e.g. ["production", "infra"].

          At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.

      • no_data object

        What the rule does when a group has no data. Required when kind is alert. Not allowed when kind is signal. Any strategy other than ignore requires either query.breach or no_data.query, so that a group with no data can be told apart from one that stopped breaching.

        One of:
        ignore object keep_last object resolve object alert object
      • query object Required

        ES|QL query the rule evaluates. base is required. breach is an optional clause appended to it.

        Additional properties are NOT allowed.

        Hide query attributes Show query attributes object
        • base string Required

          ES|QL query that specifies the data to evaluate. Must include a FROM clause. Kibana applies the time filter from schedule.lookback using time_field.

          Minimum length is 1, maximum length is 10000.

        • breach object

          Optional ES|QL clause appended to query.base. If omitted, every row from query.base is a match, and a no_data strategy other than ignore then requires no_data.query.

          Additional properties are NOT allowed.

          Hide breach attribute Show breach attribute object
          • segment string Required

            ES|QL clause appended to query.base, for example WHERE avg_cpu > 0.85. Don't include a FROM clause.

            Minimum length is 1, maximum length is 10000.

      • recovery object

        When an alert recovers. Required when kind is alert. Not allowed when kind is signal.

        One of:
        no_breach object condition object query object manual object
      • schedule object Required

        Execution schedule configuration.

        Additional properties are NOT allowed.

        Hide schedule attributes Show schedule attributes object
        • every string Required

          Execution interval, e.g. 1m, 5m, 1h.

          Maximum length is 32.

        • lookback string

          Lookback window for the query, e.g. 5m, 1h. Can also be expressed in ES|QL.

          Maximum length is 32.

      • state_transition object

        Specifies how many consecutive matches, or how long a condition must hold, before an alert becomes active or inactive. Allowed only when kind is alert.

        Additional properties are NOT allowed.

        Hide state_transition attributes Show state_transition attributes object
        • pending object

          Delay before a match opens an alert.

          Additional properties are NOT allowed.

          Hide pending attributes Show pending attributes object
          • count integer

            Consecutive matches the alert spends in pending before it becomes active on the next match. For example, 2 opens it on the third consecutive match. Set to 0 to open it on the first match.

            Minimum value is 0, maximum value is 1000.

          • operator string

            When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.

            Values are and or or.

          • timeframe string

            Duration the condition must hold, for example 5m. Combine with count using operator.

            Maximum length is 32.

        • recovering object

          Delay before a recovered match closes the alert. Has no effect when recovery.strategy is manual.

          Additional properties are NOT allowed.

          Hide recovering attributes Show recovering attributes object
          • count integer

            Consecutive recoveries the alert spends in recovering before it becomes inactive on the next recovery. For example, 2 closes it on the third consecutive recovery. Set to 0 to close it on the first recovery.

            Minimum value is 0, maximum value is 1000.

          • operator string

            When both count and timeframe are set, and requires both and or requires either. Allowed only when both fields are present.

            Values are and or or.

          • timeframe string

            Duration the condition must hold, for example 5m. Combine with count using operator.

            Maximum length is 32.

      • time_field string

        Document field Kibana uses with schedule.lookback to time-filter query.base.

        Minimum length is 1, maximum length is 256. Default value is @timestamp.

      • updated_at string(date-time) Required

        ISO timestamp when the rule was last updated.

        Format should match the following pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$.

      • updated_by object Required

        Actor who last updated the rule.

        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.

      • version integer Required

        Monotonically increasing integer number representing a rule configuration version, incremented on every change. Used on generated rule events as rule.version.

        Minimum value is 1, maximum value is 9007199254740991.

    • page number Required

      The current page number.

    • per_page number Required

      The number of rules per page.

    • total number Required

      The number of rules 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/rules 
curl \
 --request GET 'https://<KIBANA_URL>/api/alerting/v2/rules' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "items": [
    {
      "created_at": "2026-01-15T12:00:00.000Z",
      "created_by": {
        "profile_uid": "u_elastic_0"
      },
      "enabled": true,
      "grouping": {
        "fields": [
          "host.name"
        ]
      },
      "id": "rule-1",
      "kind": "alert",
      "metadata": {
        "description": "Alerts when average CPU usage exceeds a threshold.",
        "name": "Host CPU high",
        "routing_tags": [
          "sre-oncall"
        ],
        "tags": [
          "production",
          "infra"
        ]
      },
      "no_data": {
        "strategy": "keep_last"
      },
      "query": {
        "base": "FROM metrics-* | STATS avg_cpu = AVG(host.cpu.usage) BY host.name",
        "breach": {
          "segment": "WHERE avg_cpu > 0.9"
        }
      },
      "recovery": {
        "strategy": "no_breach"
      },
      "schedule": {
        "every": "1m",
        "lookback": "5m"
      },
      "state_transition": {
        "pending": {
          "count": 1
        },
        "recovering": {
          "count": 1
        }
      },
      "time_field": "@timestamp",
      "updated_at": "2026-01-15T12:00:00.000Z",
      "updated_by": {
        "profile_uid": "u_elastic_0"
      },
      "version": 1
    }
  ],
  "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."
}