List rules | Kibana API documentation

List rules Experimental; added in 9.5.0

GET /api/alerting/v2/rules

Api key auth Basic 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 1000.
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.
search string

A text string to search across rule fields.

Minimum length is 1, maximum length is 256.

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 256.
  
  type string Required
  
  Artifact type.
  
  Minimum length is 1, maximum length is 128.
  
  created_at string Required
  
  ISO timestamp when the rule was created.
  
  created_by string | null Required
  
  User who created the rule.
  
  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
  
  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.
  
  owner string
  
  Owner of the rule.
  
  Maximum length is 256.
  
  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.
  
  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.
  
  no_data_strategy string
  How the rule behaves when it finds no data for a group. If you omit this field or set it to none, those runs are ignored. If you set last_known_status or recover, a standalone query (query.format: standalone) must include query.no_data. A composed query (query.format: composed) uses query.base to detect whether data is present. The emit value is not accepted when creating or updating rules.
  
  Any of:
  string-1 string string-2 string string-3 string string-4 string
  
  Keeps the alert's last status when the rule finds no data.
  
  Value is last_known_status.
  
  Not accepted when creating or updating rules. Do not send this value.
  
  Value is emit.
  
  Marks the alert inactive the first time the rule finds no data for the alert.
  
  Value is recover.
  
  Ignores runs where the rule finds no data.
  
  Value is none.
  
  query object Required
  Detection query configuration.
  
  One of:
  composed object standalone object
  
  Composed query: a shared base with appendable breach and recovery segments.
  
  Hide attributes Show attributes
  
  base string Required
  
  Base ES|QL query. Time filters are applied automatically via the lookback window.
  
  Minimum length is 1, maximum length is 10000.
  
  breach object
  
  Breach detection configuration. Omit to treat every base row as a breach.
  
  Additional properties are NOT allowed.
  
  Hide breach attribute Show breach attribute object
  
  segment string Required
  
  A clause appended to the end of the rule's ES|QL query. Required in breach blocks.
  
  Minimum length is 1, maximum length is 10000.
  
  format string Required Discriminator
  
  Value is composed.
  
  recovery object
  
  Recovery query segment. Required when recovery_strategy is "query".
  
  Additional properties are NOT allowed.
  
  Hide recovery attribute Show recovery attribute object
  
  segment string Required
  
  Appendable ES|QL segment for recovery detection.
  
  Minimum length is 1, maximum length is 10000.
  
  Standalone queries: independent full queries for breach, recovery, and no_data.
  
  Hide attributes Show attributes
  
  breach object Required
  
  Breach detection configuration (required).
  
  Additional properties are NOT allowed.
  
  Hide breach attribute Show breach attribute object
  
  query string Required
  
  Full ES|QL query for breach detection (required).
  
  Minimum length is 1, maximum length is 10000.
  
  format string Required Discriminator
  
  Value is standalone.
  
  no_data object
  
  No-data detection query. Required when no_data_strategy is not "none".
  
  Additional properties are NOT allowed.
  
  Hide no_data attribute Show no_data attribute object
  
  query string Required
  
  Full ES|QL query that detects presence of data.
  
  Minimum length is 1, maximum length is 10000.
  
  recovery object
  
  Recovery query. Required when recovery_strategy is "query".
  
  Additional properties are NOT allowed.
  
  Hide recovery attribute Show recovery attribute object
  
  query string Required
  
  Full ES|QL query for recovery detection.
  
  Minimum length is 1, maximum length is 10000.
  
  recovery_strategy string
  The condition that marks an alert recovered. If omitted or set to none, recovery is disabled: the alert stays active even after the breach query stops returning matches, and state_transition.recovering_count / recovering_timeframe are not allowed. Set to no_breach to recover when the breach query stops returning matches. Set to query only when you also provide query.recovery.
  
  Any of:
  string-1 string string-2 string string-3 string
  
  Recovers an alert when the breach query no longer returns matches.
  
  Value is no_breach.
  
  Recovers an alert when a separate recovery query matches. Requires query.recovery.
  
  Value is query.
  
  The rule never marks an alert as recovered, even after the breach query stops returning matches.
  
  Value is none.
  
  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 | null
  
  Consecutive-match or time requirements before an alert becomes active or inactive. Applies only when kind is alert.
  
  Additional properties are NOT allowed.
  
  Hide state_transition attributes Show state_transition attributes object | null
  
  pending_count integer
  
  Number of consecutive matches required before the alert becomes active.
  
  Minimum value is 0, maximum value is 1000.
  
  pending_operator string
  
  The operator that combines pending_count and pending_timeframe. AND requires both. OR requires either.
  
  Values are AND or OR.
  
  pending_timeframe string
  
  Time window used with pending_count, for example 5m or 15m.
  
  Maximum length is 32.
  
  recovering_count integer
  
  Number of consecutive recoveries required before the alert becomes inactive.
  
  Minimum value is 0, maximum value is 1000.
  
  recovering_operator string
  
  The operator that combines recovering_count and recovering_timeframe. AND requires both. OR requires either.
  
  Values are AND or OR.
  
  recovering_timeframe string
  
  Time window used with recovering_count, for example 5m or 15m.
  
  Maximum length is 32.
  
  time_field string
  
  Document field used as the event time when applying the lookback window. Defaults to @timestamp.
  
  Minimum length is 1, maximum length is 128. Default value is @timestamp.
  
  updated_at string Required
  
  ISO timestamp when the rule was last updated.
  
  updated_by string | null Required
  
  User who last updated the rule.
  
  version string
  
  The saved object version token of the rule, used for optimistic concurrency control.
- page number Required
  
  The current page number.
- per_page number Required
  
  The number of rules per page.
- total number Required
  
  The total number of rules matching the query.
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://localhost:5601/api/alerting/v2/rules' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "items": [
    {
      "created_at": "2026-01-15T12:00:00.000Z",
      "created_by": "elastic",
      "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",
        "tags": [
          "production",
          "infra"
        ],
        "version": 1
      },
      "query": {
        "breach": {
          "query": "FROM metrics-* | WHERE host.cpu.usage > 0.9 | STATS avg_cpu = AVG(host.cpu.usage) BY host.name"
        },
        "format": "standalone"
      },
      "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": "elastic",
      "version": "WzAsMV0="
    }
  ],
  "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."
}