Alerting API

Use the Alerting API to programmatically create, update, and manage monitors and alerts. For APIs that support the composite monitor specifically, see Managing composite monitors with the API.

Create a query-level monitor

Query-level monitors run the query and determine whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see Creating monitors.

Example request

  1. POST _plugins/_alerting/monitors
  2. {
  3.   "type": "monitor",
  4.   "name": "test-monitor",
  5.   "monitor_type": "query_level_monitor",
  6.   "enabled": true,
  7.   "schedule": {
  8.     "period": {
  9.       "interval": 1,
  10.       "unit": "MINUTES"
  11.     }
  12.   },
  13.   "inputs": [{
  14.     "search": {
  15.       "indices": ["movies"],
  16.       "query": {
  17.         "size": 0,
  18.         "aggregations": {},
  19.         "query": {
  20.           "bool": {
  21.             "filter": {
  22.               "range": {
  23.                 "@timestamp": {
  24.                   "gte": "{{period_end}}||-1h",
  25.                   "lte": "{{period_end}}",
  26.                   "format": "epoch_millis"
  27.                 }
  28.               }
  29.             }
  30.           }
  31.         }
  32.       }
  33.     }
  34.   }],
  35.   "triggers": [{
  36.     "name": "test-trigger",
  37.     "severity": "1",
  38.     "condition": {
  39.       "script": {
  40.         "source": "ctx.results[0].hits.total.value > 0",
  41.         "lang": "painless"
  42.       }
  43.     },
  44.     "actions": [{
  45.       "name": "test-action",
  46.       "destination_id": "ld7912sBlQ5JUWWFThoW",
  47.       "message_template": {
  48.         "source": "This is my message body."
  49.       },
  50.       "throttle_enabled": true,
  51.       "throttle": {
  52.         "value": 27,
  53.         "unit": "MINUTES"
  54.       },
  55.       "subject_template": {
  56.         "source": "TheSubject"
  57.       }
  58.     }]
  59.   }]
  60. }

copy

If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape the quotation marks:

  1. {
  2.   "message_template": {
  3.     "source": "{ \"text\": \"Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue. - Trigger: {{ctx.trigger.name}} - Severity: {{ctx.trigger.severity}} - Period start: {{ctx.periodStart}} - Period end: {{ctx.periodEnd}}\" }"
  4.   }
  5. }

copy

Optionally, to specify a backend role, you can add the rbac_roles parameter and backend role names to the bottom of your create monitor request.

The following request creates a query-level monitor and provides two backend roles, role1 and role2. The section at the bottom of the request shows the line that specifies the roles with this syntax: "rbac_roles": ["role1", "role2"]. To learn about using backend roles to limit access, see (Advanced) Limit access by backend role.

Example request

  1. POST _plugins/_alerting/monitors
  2. {
  3.   "type": "monitor",
  4.   "name": "test-monitor",
  5.   "monitor_type": "query_level_monitor",
  6.   "enabled": true,
  7.   "schedule": {
  8.     "period": {
  9.       "interval": 1,
  10.       "unit": "MINUTES"
  11.     }
  12.   },
  13.   "inputs": [{
  14.     "search": {
  15.       "indices": ["movies"],
  16.       "query": {
  17.         "size": 0,
  18.         "aggregations": {},
  19.         "query": {
  20.           "bool": {
  21.             "filter": {
  22.               "range": {
  23.                 "@timestamp": {
  24.                   "gte": "||-1h",
  25.                   "lte": "",
  26.                   "format": "epoch_millis"
  27.                 }
  28.               }
  29.             }
  30.           }
  31.         }
  32.       }
  33.     }
  34.   }],
  35.   "triggers": [{
  36.     "name": "test-trigger",
  37.     "severity": "1",
  38.     "condition": {
  39.       "script": {
  40.         "source": "ctx.results[0].hits.total.value > 0",
  41.         "lang": "painless"
  42.       }
  43.     },
  44.     "actions": [{
  45.       "name": "test-action",
  46.       "destination_id": "ld7912sBlQ5JUWWFThoW",
  47.       "message_template": {
  48.         "source": "This is my message body."
  49.       },
  50.       "throttle_enabled": true,
  51.       "throttle": {
  52.         "value": 27,
  53.         "unit": "MINUTES"
  54.       },
  55.       "subject_template": {
  56.         "source": "TheSubject"
  57.       }
  58.     }]
  59.   }],
  60.   "rbac_roles": ["role1", "role2"]
  61. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "vd5k2GsBlQ5JUWWFxhsP",
  3.   "_version": 1,
  4.   "_seq_no": 7,
  5.   "_primary_term": 1,
  6.   "monitor": {
  7.     "type": "monitor",
  8.     "schema_version": 1,
  9.     "name": "test-monitor",
  10.     "enabled": true,
  11.     "enabled_time": 1562703611363,
  12.     "schedule": {
  13.       "period": {
  14.         "interval": 1,
  15.         "unit": "MINUTES"
  16.       }
  17.     },
  18.     "inputs": [{
  19.       "search": {
  20.         "indices": [
  21.           "movies"
  22.         ],
  23.         "query": {
  24.           "size": 0,
  25.           "query": {
  26.             "bool": {
  27.               "filter": [{
  28.                 "range": {
  29.                   "@timestamp": {
  30.                     "from": "{{period_end}}||-1h",
  31.                     "to": "{{period_end}}",
  32.                     "include_lower": true,
  33.                     "include_upper": true,
  34.                     "format": "epoch_millis",
  35.                     "boost": 1
  36.                   }
  37.                 }
  38.               }],
  39.               "adjust_pure_negative": true,
  40.               "boost": 1
  41.             }
  42.           },
  43.           "aggregations": {}
  44.         }
  45.       }
  46.     }],
  47.     "triggers": [{
  48.       "id": "ud5k2GsBlQ5JUWWFxRvi",
  49.       "name": "test-trigger",
  50.       "severity": "1",
  51.       "condition": {
  52.         "script": {
  53.           "source": "ctx.results[0].hits.total.value > 0",
  54.           "lang": "painless"
  55.         }
  56.       },
  57.       "actions": [{
  58.         "id": "ut5k2GsBlQ5JUWWFxRvj",
  59.         "name": "test-action",
  60.         "destination_id": "ld7912sBlQ5JUWWFThoW",
  61.         "message_template": {
  62.           "source": "This is my message body.",
  63.           "lang": "mustache"
  64.         },
  65.         "throttle_enabled": false,
  66.         "subject_template": {
  67.           "source": "Subject",
  68.           "lang": "mustache"
  69.         }
  70.       }]
  71.     }],
  72.     "last_update_time": 1562703611363
  73.   }
  74. }

copy

To specify a time zone, you can do so by including a cron expression with a time zone name in the schedule section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the first day of each month.

Example request

  1. {
  2.   "type": "monitor",
  3.   "name": "test-monitor",
  4.   "monitor_type": "query_level_monitor",
  5.   "enabled": true,
  6.   "schedule": {
  7.     "cron" : {
  8.         "expression": "10 12 1 * *",
  9.         "timezone": "America/Los_Angeles"
  10.     }
  11.   },
  12.   "inputs": [{
  13.     "search": {
  14.       "indices": ["movies"],
  15.       "query": {
  16.         "size": 0,
  17.         "aggregations": {},
  18.         "query": {
  19.           "bool": {
  20.             "filter": {
  21.               "range": {
  22.                 "@timestamp": {
  23.                   "gte": "{{period_end}}||-1h",
  24.                   "lte": "{{period_end}}",
  25.                   "format": "epoch_millis"
  26.                 }
  27.               }
  28.             }
  29.           }
  30.         }
  31.       }
  32.     }
  33.   }],
  34.   "triggers": [{
  35.     "name": "test-trigger",
  36.     "severity": "1",
  37.     "condition": {
  38.       "script": {
  39.         "source": "ctx.results[0].hits.total.value > 0",
  40.         "lang": "painless"
  41.       }
  42.     },
  43.     "actions": [{
  44.       "name": "test-action",
  45.       "destination_id": "ld7912sBlQ5JUWWFThoW",
  46.       "message_template": {
  47.         "source": "This is a message body."
  48.       },
  49.       "throttle_enabled": true,
  50.       "throttle": {
  51.         "value": 27,
  52.         "unit": "MINUTES"
  53.       },
  54.       "subject_template": {
  55.         "source": "Subject"
  56.       }
  57.     }]
  58.   }]
  59. }

copy

For a full list of time zone names, see List of tz database time zones. The Alerting plugin uses the Java TimeZone class to convert a ZoneId to a valid time zone.

Bucket-level monitors

Bucket-level monitors categorize results into buckets separated by fields. The monitor then runs the script with each bucket’s results and evaluates whether to trigger an alert. For more information about bucket-level and query-level monitors, see Creating monitors.

Example request

  1. POST _plugins/_alerting/monitors
  2. {
  3.   "type": "monitor",
  4.   "name": "Demo bucket-level monitor",
  5.   "monitor_type": "bucket_level_monitor",
  6.   "enabled": true,
  7.   "schedule": {
  8.     "period": {
  9.       "interval": 1,
  10.       "unit": "MINUTES"
  11.     }
  12.   },
  13.   "inputs": [
  14.     {
  15.       "search": {
  16.         "indices": [
  17.           "movies"
  18.         ],
  19.         "query": {
  20.           "size": 0,
  21.           "query": {
  22.             "bool": {
  23.               "filter": [
  24.                 {
  25.                   "range": {
  26.                     "order_date": {
  27.                       "from": "{{period_end}}||-1h",
  28.                       "to": "{{period_end}}",
  29.                       "include_lower": true,
  30.                       "include_upper": true,
  31.                       "format": "epoch_millis"
  32.                     }
  33.                   }
  34.                 }
  35.               ]
  36.             }
  37.           },
  38.           "aggregations": {
  39.             "composite_agg": {
  40.               "composite": {
  41.                 "sources": [
  42.                   {
  43.                     "user": {
  44.                       "terms": {
  45.                         "field": "user"
  46.                       }
  47.                     }
  48.                   }
  49.                 ]
  50.               },
  51.               "aggregations": {
  52.                 "avg_products_base_price": {
  53.                   "avg": {
  54.                     "field": "products.base_price"
  55.                   }
  56.                 }
  57.               }
  58.             }
  59.           }
  60.         }
  61.       }
  62.     }
  63.   ],
  64.   "triggers": [
  65.     {
  66.       "bucket_level_trigger": {
  67.         "name": "test-trigger",
  68.         "severity": "1",
  69.         "condition": {
  70.           "buckets_path": {
  71.             "_count": "_count",
  72.             "avg_products_base_price": "avg_products_base_price"
  73.           },
  74.           "parent_bucket_path": "composite_agg",
  75.           "script": {
  76.             "source": "params._count > 50 || params.avg_products_base_price < 35",
  77.             "lang": "painless"
  78.           }
  79.         },
  80.         "actions": [
  81.           {
  82.             "name": "test-action",
  83.             "destination_id": "E4o5hnsB6KjPKmHtpfCA",
  84.             "message_template": {
  85.               "source": """Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue.   - Trigger: {{ctx.trigger.name}}   - Severity: {{ctx.trigger.severity}}   - Period start: {{ctx.periodStart}}   - Period end: {{ctx.periodEnd}}    - Deduped Alerts:   {{ctx.dedupedAlerts}}     * {{id}} : {{bucket_keys}}   {{ctx.dedupedAlerts}}    - New Alerts:   {{ctx.newAlerts}}     * {{id}} : {{bucket_keys}}   {{ctx.newAlerts}}    - Completed Alerts:   {{ctx.completedAlerts}}     * {{id}} : {{bucket_keys}}   {{ctx.completedAlerts}}""",
  86.               "lang": "mustache"
  87.             },
  88.             "throttle_enabled": false,
  89.             "throttle": {
  90.               "value": 10,
  91.               "unit": "MINUTES"
  92.             },
  93.             "action_execution_policy": {
  94.               "action_execution_scope": {
  95.                 "per_alert": {
  96.                   "actionable_alerts": [
  97.                     "DEDUPED",
  98.                     "NEW"
  99.                   ]
  100.                 }
  101.               }
  102.             },
  103.             "subject_template": {
  104.               "source": "The Subject",
  105.               "lang": "mustache"
  106.             }
  107.           }
  108.         ]
  109.       }
  110.     }
  111.   ]
  112. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "Dfxr63sBwex6DxEhHV5N",
  3.   "_version" : 1,
  4.   "_seq_no" : 3,
  5.   "_primary_term" : 1,
  6.   "monitor" : {
  7.     "type" : "monitor",
  8.     "schema_version" : 4,
  9.     "name" : "Demo a bucket-level monitor",
  10.     "monitor_type" : "bucket_level_monitor",
  11.     "user" : {
  12.       "name" : "",
  13.       "backend_roles" : [ ],
  14.       "roles" : [ ],
  15.       "custom_attribute_names" : [ ],
  16.       "user_requested_tenant" : null
  17.     },
  18.     "enabled" : true,
  19.     "enabled_time" : 1631742270785,
  20.     "schedule" : {
  21.       "period" : {
  22.         "interval" : 1,
  23.         "unit" : "MINUTES"
  24.       }
  25.     },
  26.     "inputs" : [
  27.       {
  28.         "search" : {
  29.           "indices" : [
  30.             "opensearch_dashboards_sample_data_flights"
  31.           ],
  32.           "query" : {
  33.             "size" : 0,
  34.             "query" : {
  35.               "bool" : {
  36.                 "filter" : [
  37.                   {
  38.                     "range" : {
  39.                       "order_date" : {
  40.                         "from" : "{{period_end}}||-1h",
  41.                         "to" : "{{period_end}}",
  42.                         "include_lower" : true,
  43.                         "include_upper" : true,
  44.                         "format" : "epoch_millis",
  45.                         "boost" : 1.0
  46.                       }
  47.                     }
  48.                   }
  49.                 ],
  50.                 "adjust_pure_negative" : true,
  51.                 "boost" : 1.0
  52.               }
  53.             },
  54.             "aggregations" : {
  55.               "composite_agg" : {
  56.                 "composite" : {
  57.                   "size" : 10,
  58.                   "sources" : [
  59.                     {
  60.                       "user" : {
  61.                         "terms" : {
  62.                           "field" : "user",
  63.                           "missing_bucket" : false,
  64.                           "order" : "asc"
  65.                         }
  66.                       }
  67.                     }
  68.                   ]
  69.                 },
  70.                 "aggregations" : {
  71.                   "avg_products_base_price" : {
  72.                     "avg" : {
  73.                       "field" : "products.base_price"
  74.                     }
  75.                   }
  76.                 }
  77.               }
  78.             }
  79.           }
  80.         }
  81.       }
  82.     ],
  83.     "triggers" : [
  84.       {
  85.         "bucket_level_trigger" : {
  86.           "id" : "C_xr63sBwex6DxEhHV5B",
  87.           "name" : "test-trigger",
  88.           "severity" : "1",
  89.           "condition" : {
  90.             "buckets_path" : {
  91.               "_count" : "_count",
  92.               "avg_products_base_price" : "avg_products_base_price"
  93.             },
  94.             "parent_bucket_path" : "composite_agg",
  95.             "script" : {
  96.               "source" : "params._count > 50 || params.avg_products_base_price < 35",
  97.               "lang" : "painless"
  98.             },
  99.             "gap_policy" : "skip"
  100.           },
  101.           "actions" : [
  102.             {
  103.               "id" : "DPxr63sBwex6DxEhHV5B",
  104.               "name" : "test-action",
  105.               "destination_id" : "E4o5hnsB6KjPKmHtpfCA",
  106.               "message_template" : {
  107.                 "source" : "Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue.   - Trigger: {{ctx.trigger.name}}   - Severity: {{ctx.trigger.severity}}   - Period start: {{ctx.periodStart}}   - Period end: {{ctx.periodEnd}}    - Deduped Alerts:   {{ctx.dedupedAlerts}}     * {{id}} : {{bucket_keys}}   {{ctx.dedupedAlerts}}    - New Alerts:   {{ctx.newAlerts}}     * {{id}} : {{bucket_keys}}   {{ctx.newAlerts}}    - Completed Alerts:   {{ctx.completedAlerts}}     * {{id}} : {{bucket_keys}}   {{ctx.completedAlerts}}",
  108.                 "lang" : "mustache"
  109.               },
  110.               "throttle_enabled" : false,
  111.               "subject_template" : {
  112.                 "source" : "The Subject",
  113.                 "lang" : "mustache"
  114.               },
  115.               "throttle" : {
  116.                 "value" : 10,
  117.                 "unit" : "MINUTES"
  118.               },
  119.               "action_execution_policy" : {
  120.                 "action_execution_scope" : {
  121.                   "per_alert" : {
  122.                     "actionable_alerts" : [
  123.                       "DEDUPED",
  124.                       "NEW"
  125.                     ]
  126.                   }
  127.                 }
  128.               }
  129.             }
  130.           ]
  131.         }
  132.       }
  133.     ],
  134.     "last_update_time" : 1631742270785
  135.   }
  136. }

copy

Document-level monitors

Introduced 2.0

Document-level monitors check whether individual documents in an index match trigger conditions. If so, the monitor generates an alert notification. When you run a query with a document-level monitor, the results are returned for each document that matches the trigger condition. You can create trigger conditions based on query names, query IDs, or tags that combine multiple queries.

To learn more about per document monitors that function similarly to the document-level monitor API, see Monitors.

Search the findings index

You can use the Alerting search API operation to search the findings index .opensearch-alerting-finding* for available document findings with a GET request. By default, a GET request without path parameters returns all available findings.

To retrieve any available findings, send a GET request without any path parameters as follows:

  1. GET /_plugins/_alerting/findings/_search?

copy

To retrieve metadata for an individual document finding entry, you can search for the finding by its findingId as follows:

  1. GET /_plugins/_alerting/findings/_search?findingId=gKQhj8WJit3BxjGfiOXC

copy

The response returns the number of individual finding entries in the total_findings field.

To get more specific results in a findings search, you can use any of the optional path parameters defined in the following table.

Path parameterDescriptionUsage
findingIdThe identifier for the finding entry.The finding ID is returned in the initial query response.
sortStringThis field specifies which string the Alerting plugin uses to sort the findings.The default value is id.
sortOrderThe order to sort the list of findings, either ascending or descending.Use sortOrder=asc to indicate ascending, or sortOrder=desc for descending sort order.
sizeAn optional limit for the maximum number of results returned in the response.There is no minimum or maximum values.
startIndexThe pagination indicator.Default is 0.
searchStringThe finding attribute you want returned in the search.To search in a specific index, specify the index name in the request path. For example, to search findings in the indexABC index, use `searchString=indexABC’.

Create a document-level monitor

You can create a document-level monitor with a POST request that provides the monitor details in the request body. At a minimum, you need to provide the following details: specify the queries or combinations by tag with the inputs field, a valid trigger condition, and provide the notification message in the action field.

The following table provides the syntax to use for each trigger option.

Trigger optionsDefinitionSyntax
TagCreates alerts for documents that match a multiple query with this tag applied. If you group multiple queries by a single tag, then you can set it to trigger an alert if the results are returned by this tag name.query[tag=<tag-name>]
Query by nameCreates alerts for documents matched or returned by the named query.query[name=<query-name>]
Query by IDCreates alerts for documents that were returned by the identified query.query[id=<query-id>]

Example request

  1. POST _plugins/_alerting/monitors
  2. {
  3.   "type": "monitor",
  4.   "monitor_type": "doc_level_monitor",
  5.   "name": "Example document-level monitor",
  6.   "enabled": true,
  7.   "schedule": {
  8.     "period": {
  9.       "interval": 1,
  10.       "unit": "MINUTES"
  11.     }
  12.   },
  13.   "inputs": [
  14.     {
  15.       "doc_level_input": {
  16.         "description": "Example document-level monitor for audit logs",
  17.         "indices": [
  18.           "audit-logs"
  19.         ],
  20.         "queries": [
  21.         {
  22.             "id": "nKQnFYABit3BxjGfiOXC",
  23.             "name": "sigma-123",
  24.             "query": "region:\"us-west-2\"",
  25.             "tags": [
  26.                 "tag1"
  27.             ]
  28.         },
  29.         {
  30.             "id": "gKQnABEJit3BxjGfiOXC",
  31.             "name": "sigma-456",
  32.             "query": "region:\"us-east-1\"",
  33.             "tags": [
  34.                 "tag2"
  35.             ]
  36.         },
  37.         {
  38.             "id": "h4J2ABEFNW3vxjGfiOXC",
  39.             "name": "sigma-789",
  40.             "query": "message:\"This is a SEPARATE error from IAD region\"",
  41.             "tags": [
  42.                 "tag3"
  43.             ]
  44.         }
  45.     ]
  46.       }
  47.     }
  48.   ],
  49.     "triggers": [ { "document_level_trigger": {
  50.       "name": "test-trigger",
  51.       "severity": "1",
  52.       "condition": {
  53.         "script": {
  54.           "source": "(query[name=sigma-123] || query[tag=tag3]) && query[name=sigma-789]",
  55.           "lang": "painless"
  56.         }
  57.       },
  58.       "actions": [
  59.         {
  60.             "name": "test-action",
  61.             "destination_id": "E4o5hnsB6KjPKmHtpfCA",
  62.             "message_template": {
  63.                 "source": """Monitor  just entered alert status. Please investigate the issue. Related Finding Ids: {{ctx.alerts.0.finding_ids}}, Related Document Ids: {{ctx.alerts.0.related_doc_ids}}""",
  64.                 "lang": "mustache"
  65.             },
  66.             "action_execution_policy": {
  67.                 "action_execution_scope": {
  68.                     "per_alert": {
  69.                         "actionable_alerts": []
  70.                     }
  71.                 }
  72.             },
  73.             "subject_template": {
  74.                 "source": "The Subject",
  75.                 "lang": "mustache"
  76.             }
  77.          }
  78.       ]
  79.   }}]
  80. }

copy

Limitations

If you run a document-level query while the index is getting reindexed, the API response will not return the reindexed results. To get updates, wait until the reindexing process completes, then rerun the query.

Update monitor

When updating a monitor, you can optionally include seq_no and primary_term as parameters. If these numbers do not match the existing monitor or the monitor does not exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response).

Example request

  1. PUT _plugins/_alerting/monitors/<monitor_id>
  2. {
  3.   "type": "monitor",
  4.   "name": "test-monitor",
  5.   "enabled": true,
  6.   "enabled_time": 1551466220455,
  7.   "schedule": {
  8.     "period": {
  9.       "interval": 1,
  10.       "unit": "MINUTES"
  11.     }
  12.   },
  13.   "inputs": [{
  14.     "search": {
  15.       "indices": [
  16.         "*"
  17.       ],
  18.       "query": {
  19.         "query": {
  20.           "match_all": {
  21.             "boost": 1
  22.           }
  23.         }
  24.       }
  25.     }
  26.   }],
  27.   "triggers": [{
  28.     "id": "StaeOmkBC25HCRGmL_y-",
  29.     "name": "test-trigger",
  30.     "severity": "1",
  31.     "condition": {
  32.       "script": {
  33.         "source": "return true",
  34.         "lang": "painless"
  35.       }
  36.     },
  37.     "actions": [{
  38.       "name": "test-action",
  39.       "destination_id": "RtaaOmkBC25HCRGm0fxi",
  40.       "subject_template": {
  41.         "source": "My Message Subject",
  42.         "lang": "mustache"
  43.       },
  44.       "message_template": {
  45.         "source": "This is my message body.",
  46.         "lang": "mustache"
  47.       }
  48.     }]
  49.   }],
  50.   "last_update_time": 1551466639295
  51. }
  53. PUT _plugins/_alerting/monitors/<monitor_id>?if_seq_no=3&if_primary_term=1
  54. {
  55.   "type": "monitor",
  56.   "name": "test-monitor",
  57.   "enabled": true,
  58.   "enabled_time": 1551466220455,
  59.   "schedule": {
  60.     "period": {
  61.       "interval": 1,
  62.       "unit": "MINUTES"
  63.     }
  64.   },
  65.   "inputs": [{
  66.     "search": {
  67.       "indices": [
  68.         "*"
  69.       ],
  70.       "query": {
  71.         "query": {
  72.           "match_all": {
  73.             "boost": 1
  74.           }
  75.         }
  76.       }
  77.     }
  78.   }],
  79.   "triggers": [{
  80.     "id": "StaeOmkBC25HCRGmL_y-",
  81.     "name": "test-trigger",
  82.     "severity": "1",
  83.     "condition": {
  84.       "script": {
  85.         "source": "return true",
  86.         "lang": "painless"
  87.       }
  88.     },
  89.     "actions": [{
  90.       "name": "test-action",
  91.       "destination_id": "RtaaOmkBC25HCRGm0fxi",
  92.       "subject_template": {
  93.         "source": "My Message Subject",
  94.         "lang": "mustache"
  95.       },
  96.       "message_template": {
  97.         "source": "This is my message body.",
  98.         "lang": "mustache"
  99.       }
  100.     }]
  101.   }],
  102.   "last_update_time": 1551466639295
  103. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "Q9aXOmkBC25HCRGmzfw-",
  3.   "_version": 4,
  4.   "_seq_no": 4,
  5.   "_primary_term": 1,
  6.   "monitor": {
  7.     "type": "monitor",
  8.     "name": "test-monitor",
  9.     "enabled": true,
  10.     "enabled_time": 1551466220455,
  11.     "schedule": {
  12.       "period": {
  13.         "interval": 1,
  14.         "unit": "MINUTES"
  15.       }
  16.     },
  17.     "inputs": [{
  18.       "search": {
  19.         "indices": [
  20.           "*"
  21.         ],
  22.         "query": {
  23.           "query": {
  24.             "match_all": {
  25.               "boost": 1
  26.             }
  27.           }
  28.         }
  29.       }
  30.     }],
  31.     "triggers": [{
  32.       "id": "StaeOmkBC25HCRGmL_y-",
  33.       "name": "test-trigger",
  34.       "severity": "1",
  35.       "condition": {
  36.         "script": {
  37.           "source": "return true",
  38.           "lang": "painless"
  39.         }
  40.       },
  41.       "actions": [{
  42.         "name": "test-action",
  43.         "destination_id": "RtaaOmkBC25HCRGm0fxi",
  44.         "subject_template": {
  45.           "source": "My Message Subject",
  46.           "lang": "mustache"
  47.         },
  48.         "message_template": {
  49.           "source": "This is my message body.",
  50.           "lang": "mustache"
  51.         }
  52.       }]
  53.     }],
  54.     "last_update_time": 1551466761596
  55.   }
  56. }

copy

Get monitor

Retrieve the details of a specific monitor using the following request.

Example request

  1. GET _plugins/_alerting/monitors/<monitor_id>

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "Q9aXOmkBC25HCRGmzfw-",
  3.   "_version": 3,
  4.   "_seq_no": 3,
  5.   "_primary_term": 1,
  6.   "monitor": {
  7.     "type": "monitor",
  8.     "name": "test-monitor",
  9.     "enabled": true,
  10.     "enabled_time": 1551466220455,
  11.     "schedule": {
  12.       "period": {
  13.         "interval": 1,
  14.         "unit": "MINUTES"
  15.       }
  16.     },
  17.     "inputs": [{
  18.       "search": {
  19.         "indices": [
  20.           "*"
  21.         ],
  22.         "query": {
  23.           "query": {
  24.             "match_all": {
  25.               "boost": 1
  26.             }
  27.           }
  28.         }
  29.       }
  30.     }],
  31.     "triggers": [{
  32.       "id": "StaeOmkBC25HCRGmL_y-",
  33.       "name": "test-trigger",
  34.       "severity": "1",
  35.       "condition": {
  36.         "script": {
  37.           "source": "return true",
  38.           "lang": "painless"
  39.         }
  40.       },
  41.       "actions": [{
  42.         "name": "test-action",
  43.         "destination_id": "RtaaOmkBC25HCRGm0fxi",
  44.         "subject_template": {
  45.           "source": "My Message Subject",
  46.           "lang": "mustache"
  47.         },
  48.         "message_template": {
  49.           "source": "This is my message body.",
  50.           "lang": "mustache"
  51.         }
  52.       }]
  53.     }],
  54.     "last_update_time": 1551466639295
  55.   }
  56. }

copy

Monitor stats

Returns statistics about the alerting feature. Use _plugins/_alerting/stats to find node IDs and metrics. Then you can drill down using those values.

Example request

  1. GET _plugins/_alerting/stats
  2. GET _plugins/_alerting/stats/<metric>
  3. GET _plugins/_alerting/<node-id>/stats
  4. GET _plugins/_alerting/<node-id>/stats/<metric>

copy

Select to expand example response

Example response

  1. {
  2.   "_nodes": {
  3.     "total": 9,
  4.     "successful": 9,
  5.     "failed": 0
  6.   },
  7.   "cluster_name": "475300751431:alerting65-dont-delete",
  8.   "plugins.scheduled_jobs.enabled": true,
  9.   "scheduled_job_index_exists": true,
  10.   "scheduled_job_index_status": "green",
  11.   "nodes_on_schedule": 9,
  12.   "nodes_not_on_schedule": 0,
  13.   "nodes": {
  14.     "qWcbKbb-TVyyI-Q7VSeOqA": {
  15.       "name": "qWcbKbb",
  16.       "schedule_status": "green",
  17.       "roles": [
  18.         "MASTER"
  19.       ],
  20.       "job_scheduling_metrics": {
  21.         "last_full_sweep_time_millis": 207017,
  22.         "full_sweep_on_time": true
  23.       },
  24.       "jobs_info": {}
  25.     },
  26.     "Do-DX9ZcS06Y9w1XbSJo1A": {
  27.       "name": "Do-DX9Z",
  28.       "schedule_status": "green",
  29.       "roles": [
  30.         "DATA",
  31.         "INGEST"
  32.       ],
  33.       "job_scheduling_metrics": {
  34.         "last_full_sweep_time_millis": 230516,
  35.         "full_sweep_on_time": true
  36.       },
  37.       "jobs_info": {}
  38.     },
  39.     "n5phkBiYQfS5I0FDzcqjZQ": {
  40.       "name": "n5phkBi",
  41.       "schedule_status": "green",
  42.       "roles": [
  43.         "MASTER"
  44.       ],
  45.       "job_scheduling_metrics": {
  46.         "last_full_sweep_time_millis": 228406,
  47.         "full_sweep_on_time": true
  48.       },
  49.       "jobs_info": {}
  50.     },
  51.     "Tazzo8cQSY-g3vOjgYYLzA": {
  52.       "name": "Tazzo8c",
  53.       "schedule_status": "green",
  54.       "roles": [
  55.         "DATA",
  56.         "INGEST"
  57.       ],
  58.       "job_scheduling_metrics": {
  59.         "last_full_sweep_time_millis": 211722,
  60.         "full_sweep_on_time": true
  61.       },
  62.       "jobs_info": {
  63.         "i-wsFmkB8NzS6aXjQSk0": {
  64.           "last_execution_time": 1550864912882,
  65.           "running_on_time": true
  66.         }
  67.       }
  68.     },
  69.     "Nyf7F8brTOSJuFPXw6CnpA": {
  70.       "name": "Nyf7F8b",
  71.       "schedule_status": "green",
  72.       "roles": [
  73.         "DATA",
  74.         "INGEST"
  75.       ],
  76.       "job_scheduling_metrics": {
  77.         "last_full_sweep_time_millis": 223300,
  78.         "full_sweep_on_time": true
  79.       },
  80.       "jobs_info": {
  81.         "NbpoFmkBeSe-hD59AKgE": {
  82.           "last_execution_time": 1550864928354,
  83.           "running_on_time": true
  84.         },
  85.         "-LlLFmkBeSe-hD59Ydtb": {
  86.           "last_execution_time": 1550864732727,
  87.           "running_on_time": true
  88.         },
  89.         "pBFxFmkBNXkgNmTBaFj1": {
  90.           "last_execution_time": 1550863325024,
  91.           "running_on_time": true
  92.         },
  93.         "hfasEmkBNXkgNmTBrvIW": {
  94.           "last_execution_time": 1550862000001,
  95.           "running_on_time": true
  96.         }
  97.       }
  98.     },
  99.     "oOdJDIBVT5qbbO3d8VLeEw": {
  100.       "name": "oOdJDIB",
  101.       "schedule_status": "green",
  102.       "roles": [
  103.         "DATA",
  104.         "INGEST"
  105.       ],
  106.       "job_scheduling_metrics": {
  107.         "last_full_sweep_time_millis": 227570,
  108.         "full_sweep_on_time": true
  109.       },
  110.       "jobs_info": {
  111.         "4hKRFmkBNXkgNmTBKjYX": {
  112.           "last_execution_time": 1550864806101,
  113.           "running_on_time": true
  114.         }
  115.       }
  116.     },
  117.     "NRDG6JYgR8m0GOZYQ9QGjQ": {
  118.       "name": "NRDG6JY",
  119.       "schedule_status": "green",
  120.       "roles": [
  121.         "MASTER"
  122.       ],
  123.       "job_scheduling_metrics": {
  124.         "last_full_sweep_time_millis": 227652,
  125.         "full_sweep_on_time": true
  126.       },
  127.       "jobs_info": {}
  128.     },
  129.     "URMrXRz3Tm-CB72hlsl93Q": {
  130.       "name": "URMrXRz",
  131.       "schedule_status": "green",
  132.       "roles": [
  133.         "DATA",
  134.         "INGEST"
  135.       ],
  136.       "job_scheduling_metrics": {
  137.         "last_full_sweep_time_millis": 231048,
  138.         "full_sweep_on_time": true
  139.       },
  140.       "jobs_info": {
  141.         "m7uKFmkBeSe-hD59jplP": {
  142.           "running_on_time": true
  143.         }
  144.       }
  145.     },
  146.     "eXgt1k9oTRCLmx2HBGElUw": {
  147.       "name": "eXgt1k9",
  148.       "schedule_status": "green",
  149.       "roles": [
  150.         "DATA",
  151.         "INGEST"
  152.       ],
  153.       "job_scheduling_metrics": {
  154.         "last_full_sweep_time_millis": 229234,
  155.         "full_sweep_on_time": true
  156.       },
  157.       "jobs_info": {
  158.         "wWkFFmkBc2NG-PeLntxk": {
  159.           "running_on_time": true
  160.         },
  161.         "3usNFmkB8NzS6aXjO1Gs": {
  162.           "last_execution_time": 1550863959848,
  163.           "running_on_time": true
  164.         }
  165.       }
  166.     }
  167.   }
  168. }

copy

Delete monitor

Delete a monitor using the following request.

Example request

  1. DELETE _plugins/_alerting/monitors/<monitor_id>

copy

Select to expand example response

Example response

  1. {
  2.   "_index": ".opensearch-scheduled-jobs",
  3.   "_id": "OYAHOmgBl3cmwnqZl_yH",
  4.   "_version": 2,
  5.   "result": "deleted",
  6.   "forced_refresh": true,
  7.   "_shards": {
  8.     "total": 2,
  9.     "successful": 2,
  10.     "failed": 0
  11.   },
  12.   "_seq_no": 11,
  13.   "_primary_term": 1
  14. }

copy

Search monitors

Query and retrieve information about existing monitors based on specific criteria, such as the monitor name, using the following request.

Example request

  1. GET _plugins/_alerting/monitors/_search
  2. {
  3.   "query": {
  4.     "match" : {
  5.       "monitor.name": "my-monitor-name"
  6.     }
  7.   }
  8. }

copy

Select to expand example response

Example response

  1. {
  2.   "took": 17,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 5,
  6.     "successful": 5,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": 1,
  12.     "max_score": 0.6931472,
  13.     "hits": [{
  14.       "_index": ".opensearch-scheduled-jobs",
  15.       "_type": "_doc",
  16.       "_id": "eGQi7GcBRS7-AJEqfAnr",
  17.       "_score": 0.6931472,
  18.       "_source": {
  19.         "type": "monitor",
  20.         "name": "my-monitor-name",
  21.         "enabled": true,
  22.         "enabled_time": 1545854942426,
  23.         "schedule": {
  24.           "period": {
  25.             "interval": 1,
  26.             "unit": "MINUTES"
  27.           }
  28.         },
  29.         "inputs": [{
  30.           "search": {
  31.             "indices": [
  32.               "*"
  33.             ],
  34.             "query": {
  35.               "size": 0,
  36.               "query": {
  37.                 "bool": {
  38.                   "filter": [{
  39.                     "range": {
  40.                       "@timestamp": {
  41.                         "from": "{{period_end}}||-1h",
  42.                         "to": "{{period_end}}",
  43.                         "include_lower": true,
  44.                         "include_upper": true,
  45.                         "format": "epoch_millis",
  46.                         "boost": 1
  47.                       }
  48.                     }
  49.                   }],
  50.                   "adjust_pure_negative": true,
  51.                   "boost": 1
  52.                 }
  53.               },
  54.               "aggregations": {}
  55.             }
  56.           }
  57.         }],
  58.         "triggers": [{
  59.           "id": "Sooi7GcB53a0ewuj_6MH",
  60.           "name": "Over",
  61.           "severity": "1",
  62.           "condition": {
  63.             "script": {
  64.               "source": "_ctx.results[0].hits.total > 400000",
  65.               "lang": "painless"
  66.             }
  67.           },
  68.           "actions": []
  69.         }],
  70.         "last_update_time": 1545854975758
  71.       }
  72.     }]
  73.   }
  74. }

copy

Run monitor

You can add the optional ?dryrun=true parameter to the URL to show the results of a run without actions sending any message.

Example request

  1. POST _plugins/_alerting/monitors/<monitor_id>/_execute

copy

Select to expand example response

Example response

  1. {
  2.   "monitor_name": "logs",
  3.   "period_start": 1547161872322,
  4.   "period_end": 1547161932322,
  5.   "error": null,
  6.   "trigger_results": {
  7.     "Sooi7GcB53a0ewuj_6MH": {
  8.       "name": "Over",
  9.       "triggered": true,
  10.       "error": null,
  11.       "action_results": {}
  12.     }
  13.   }
  14. }

copy

Get alerts

Return an array of all alerts.

Path parameters

The following table lists the available path parameters. All path parameters are optional.

ParameterData typeDescription
sortStringStringDefines how to sort the results. Default is monitor_name.keyword.
sortOrderStringDefines the order of the results. Options are asc or desc. Default is asc.
missingStringSpecifies whether to include missing data in the response.
sizeStringDefines the size of the request to be returned. Default is 20.
startIndexStringDefines the index to start from. Used for paginating results. Default is 0.
searchStringStringDefines the search string to use for searching a specific alert. Default is an empty string.
severityLevelStringDefines the severity level to filter for. Default is ALL.
alertStateStringDefines the alert state to filter for. Default is ALL.
monitorIdStringFilters by monitor ID.
workflowIdsStringAllows for monitoring the status of chained alerts from multiple workflows within a single dashboard. Available in OpenSearch 2.9 or later.

Example request

  1. GET _plugins/_alerting/monitors/alerts

copy

Select to expand example response

Example response

  1. {
  2.   "alerts": [
  3.     {
  4.       "id": "eQURa3gBKo1jAh6qUo49",
  5.       "version": 300,
  6.       "monitor_id": "awUMa3gBKo1jAh6qu47E",
  7.       "schema_version": 2,
  8.       "monitor_version": 2,
  9.       "monitor_name": "Example_monitor_name",
  10.       "monitor_user": {
  11.         "name": "admin",
  12.         "backend_roles": [
  13.           "admin"
  14.         ],
  15.         "roles": [
  16.           "all_access",
  17.           "own_index"
  18.         ],
  19.         "custom_attribute_names": [],
  20.         "user_requested_tenant": null
  21.       },
  22.       "trigger_id": "bQUQa3gBKo1jAh6qnY6G",
  23.       "trigger_name": "Example_trigger_name",
  24.       "state": "ACTIVE",
  25.       "error_message": null,
  26.       "alert_history": [
  27.         {
  28.           "timestamp": 1617314504873,
  29.           "message": "Example error message"
  30.         },
  31.         {
  32.           "timestamp": 1617312543925,
  33.           "message": "Example error message"
  34.         }
  35.       ],
  36.       "severity": "1",
  37.       "action_execution_results": [
  38.         {
  39.           "action_id": "bgUQa3gBKo1jAh6qnY6G",
  40.           "last_execution_time": 1617317979908,
  41.           "throttled_count": 0
  42.         }
  43.       ],
  44.       "start_time": 1616704000492,
  45.       "last_notification_time": 1617317979908,
  46.       "end_time": null,
  47.       "acknowledged_time": null
  48.     }
  49.   ],
  50.   "totalAlerts": 1
  51. }

copy

Acknowledge alert

After getting your alerts, you can acknowledge any number of active alerts in one call. If the alert is already in an ERROR, COMPLETED, or ACKNOWLEDGED state, it appears in the failed array.

Example request

  1. POST _plugins/_alerting/monitors/<monitor-id>/_acknowledge/alerts
  2. {
  3.   "alerts": ["eQURa3gBKo1jAh6qUo49"]
  4. }

copy

Select to expand example response

Example response

  1. {
  2.   "success": [
  3.   "eQURa3gBKo1jAh6qUo49"
  4.   ],
  5.   "failed": []
  6. }

copy

Create destination

Define and configure various destinations for receiving alert notifications using the following request. These destinations can be of different types, such as Slack, custom webhooks, or email, and are used to specify where and how alerts should be delivered.

Example request

  1. POST _plugins/_alerting/destinations
  2. {
  3.   "name": "my-destination",
  4.   "type": "slack",
  5.   "slack": {
  6.     "url": "http://www.example.com"
  7.   }
  8. }
  10. POST _plugins/_alerting/destinations
  11. {
  12.   "type": "custom_webhook",
  13.   "name": "my-custom-destination",
  14.   "custom_webhook": {
  15.     "path": "incomingwebhooks/123456-123456-XXXXXX",
  16.     "header_params": {
  17.       "Content-Type": "application/json"
  18.     },
  19.     "scheme": "HTTPS",
  20.     "port": 443,
  21.     "query_params": {
  22.       "token": "R2x1UlN4ZHF8MXxxVFJpelJNVDgzdGNwXXXXXXXXX"
  23.     },
  24.     "host": "hooks.chime.aws"
  25.   }
  26. }
  28. POST _plugins/_alerting/destinations
  29. {
  30.   "type": "email",
  31.   "name": "my-email-destination",
  32.   "email": {
  33.     "email_account_id": "YjY7mXMBx015759_IcfW",
  34.     "recipients": [
  35.       {
  36.         "type": "email_group",
  37.         "email_group_id": "YzY-mXMBx015759_dscs"
  38.       },
  39.       {
  40.         "type": "email",
  41.         "email": "example@email.com"
  42.       }
  43.     ]
  44.   }
  45. }
  47. // The email_account_id and email_group_id will be the document IDs of the email_account and email_group you have created.

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "nO-yFmkB8NzS6aXjJdiI",
  3.   "_version" : 1,
  4.   "_seq_no" : 3,
  5.   "_primary_term" : 1,
  6.   "destination": {
  7.     "type": "slack",
  8.     "name": "my-destination",
  9.     "last_update_time": 1550863967624,
  10.     "slack": {
  11.       "url": "http://www.example.com"
  12.     }
  13.   }
  14. }

copy

Update destination

When updating a destination, you can optionally include seq_no and primary_term as parameters. If these numbers do not match the existing destination or the destination doesn’t exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response).

Example request

  1. PUT _plugins/_alerting/destinations/<destination-id>
  2. {
  3.   "name": "my-updated-destination",
  4.   "type": "slack",
  5.   "slack": {
  6.     "url": "http://www.example.com"
  7.   }
  8. }
  10. PUT _plugins/_alerting/destinations/<destination-id>?if_seq_no=3&if_primary_term=1
  11. {
  12.   "name": "my-updated-destination",
  13.   "type": "slack",
  14.   "slack": {
  15.     "url": "http://www.example.com"
  16.   }
  17. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "pe-1FmkB8NzS6aXjqvVY",
  3.   "_version" : 2,
  4.   "_seq_no" : 4,
  5.   "_primary_term" : 1,
  6.   "destination": {
  7.     "type": "slack",
  8.     "name": "my-updated-destination",
  9.     "last_update_time": 1550864289375,
  10.     "slack": {
  11.       "url": "http://www.example.com"
  12.     }
  13.   }
  14. }

copy

Get destination

Retrieve one destination using the following request.

Example request

  1. GET _plugins/_alerting/destinations/<destination-id>

copy

Select to expand example response

Example response

  1. {
  2.   "totalDestinations": 1,
  3.   "destinations": [{
  4.       "id": "1a2a3a4a5a6a7a",
  5.       "type": "slack",
  6.       "name": "sample-destination",
  7.       "user": {
  8.         "name": "psantos",
  9.         "backend_roles": [
  10.           "human-resources"
  11.         ],
  12.         "roles": [
  13.           "alerting_full_access",
  14.           "hr-role"
  15.         ],
  16.         "custom_attribute_names": []
  17.       },
  18.       "schema_version": 3,
  19.       "seq_no": 0,
  20.       "primary_term": 6,
  21.       "last_update_time": 1603943261722,
  22.       "slack": {
  23.         "url": "https://example.com"
  24.       }
  25.     }
  26.   ]
  27. }

copy

Get destinations

Retrieve all destinations using the following request.

Example request

  1. GET _plugins/_alerting/destinations

copy

Select to expand example response

Example response

  1. {
  2.   "totalDestinations": 1,
  3.   "destinations": [{
  4.       "id": "1a2a3a4a5a6a7a",
  5.       "type": "slack",
  6.       "name": "sample-destination",
  7.       "user": {
  8.         "name": "psantos",
  9.         "backend_roles": [
  10.           "human-resources"
  11.         ],
  12.         "roles": [
  13.           "alerting_full_access",
  14.           "hr-role"
  15.         ],
  16.         "custom_attribute_names": []
  17.       },
  18.       "schema_version": 3,
  19.       "seq_no": 0,
  20.       "primary_term": 6,
  21.       "last_update_time": 1603943261722,
  22.       "slack": {
  23.         "url": "https://example.com"
  24.       }
  25.     }
  26.   ]
  27. }

copy

Delete destination

Remove a specific destination from the alerting system using the following request.

Example request

  1. DELETE _plugins/_alerting/destinations/<destination-id>

copy

Select to expand example response

Example response

  1. {
  2.   "_index": ".opendistro-alerting-config",
  3.   "_type": "_doc",
  4.   "_id": "Zu-zFmkB8NzS6aXjLeBI",
  5.   "_version": 2,
  6.   "result": "deleted",
  7.   "forced_refresh": true,
  8.   "_shards": {
  9.     "total": 2,
  10.     "successful": 2,
  11.     "failed": 0
  12.   },
  13.   "_seq_no": 8,
  14.   "_primary_term": 1
  15. }

copy

Create email account

Set up a new email account for sending alert notifications using the following request.

Example request

  1. POST _plugins/_alerting/destinations/email_accounts
  2. {
  3.   "name": "example_account",
  4.   "email": "example@email.com",
  5.   "host": "smtp.email.com",
  6.   "port": 465,
  7.   "method": "ssl"
  8. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "email_account_id",
  3.   "_version" : 1,
  4.   "_seq_no" : 7,
  5.   "_primary_term" : 2,
  6.   "email_account" : {
  7.     "schema_version" : 2,
  8.     "name" : "example_account",
  9.     "email" : "example@email.com",
  10.     "host" : "smtp.email.com",
  11.     "port" : 465,
  12.     "method" : "ssl"
  13.   }
  14. }

copy

Update email account

When updating an email account, you can optionally include seq_no and primary_term as parameters. If these numbers don’t match the existing email account or the email account doesn’t exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response).

Example request

  1. PUT _plugins/_alerting/destinations/email_accounts/<email_account_id>
  2. {
  3.   "name": "example_account",
  4.   "email": "example@email.com",
  5.   "host": "smtp.email.com",
  6.   "port": 465,
  7.   "method": "ssl"
  8. }
  10. PUT _plugins/_alerting/destinations/email_accounts/<email_account_id>?if_seq_no=18&if_primary_term=2
  11. {
  12.   "name": "example_account",
  13.   "email": "example@email.com",
  14.   "host": "smtp.email.com",
  15.   "port": 465,
  16.   "method": "ssl"
  17. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "email_account_id",
  3.   "_version" : 3,
  4.   "_seq_no" : 19,
  5.   "_primary_term" : 2,
  6.   "email_account" : {
  7.     "schema_version" : 2,
  8.     "name" : "example_account",
  9.     "email" : "example@email.com",
  10.     "host" : "smtp.email.com",
  11.     "port" : 465,
  12.     "method" : "ssl"
  13.   }
  14. }

copy

Get email account

Retrieve the details of a specific email account configured for alerting purposes using the following request.

Example request

  1. GET _plugins/_alerting/destinations/email_accounts/<email_account_id>
  2. {
  3.   "name": "example_account",
  4.   "email": "example@email.com",
  5.   "host": "smtp.email.com",
  6.   "port": 465,
  7.   "method": "ssl"
  8. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "email_account_id",
  3.   "_version" : 2,
  4.   "_seq_no" : 8,
  5.   "_primary_term" : 2,
  6.   "email_account" : {
  7.     "schema_version" : 2,
  8.     "name" : "test_account",
  9.     "email" : "test@email.com",
  10.     "host" : "smtp.test.com",
  11.     "port" : 465,
  12.     "method" : "ssl"
  13.   }
  14. }

copy

Delete email account

Remove an existing email account configuration from the alerting system using the following request.

Example request

  1. DELETE _plugins/_alerting/destinations/email_accounts/<email_account_id>

copy

Select to expand example response

Example response

  1. {
  2.   "_index" : ".opendistro-alerting-config",
  3.   "_type" : "_doc",
  4.   "_id" : "email_account_id",
  5.   "_version" : 1,
  6.   "result" : "deleted",
  7.   "forced_refresh" : true,
  8.   "_shards" : {
  9.     "total" : 2,
  10.     "successful" : 2,
  11.     "failed" : 0
  12.   },
  13.   "_seq_no" : 12,
  14.   "_primary_term" : 2
  15. }

copy

Search email account

Retrieve information about the configured email accounts used for email-based alerting using the following request.

Example request

  1. POST _plugins/_alerting/destinations/email_accounts/_search
  2. {
  3.   "from": 0,
  4.   "size": 20,
  5.   "sort": { "email_account.name.keyword": "desc" },
  6.   "query": {
  7.     "bool": {
  8.       "must": {
  9.         "match_all": {}
  10.       }
  11.     }
  12.   }
  13. }

copy

Select to expand example response

Example response

  1. {
  2.   "took" : 8,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 2,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : null,
  16.     "hits" : [
  17.       {
  18.         "_index" : ".opendistro-alerting-config",
  19.         "_type" : "_doc",
  20.         "_id" : "email_account_id",
  21.         "_seq_no" : 8,
  22.         "_primary_term" : 2,
  23.         "_score" : null,
  24.         "_source" : {
  25.           "schema_version" : 2,
  26.           "name" : "example_account",
  27.           "email" : "example@email.com",
  28.           "host" : "smtp.email.com",
  29.           "port" : 465,
  30.           "method" : "ssl"
  31.         },
  32.         "sort" : [
  33.           "example_account"
  34.         ]
  35.       },
  36.       ...
  37.     ]
  38.   }
  39. }

copy

Create email group

Define a new group of email recipients for alerts using the following request.

Example request

  1. POST _plugins/_alerting/destinations/email_groups
  2. {
  3.   "name": "example_email_group",
  4.   "emails": [{
  5.     "email": "example@email.com"
  6.   }]
  7. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "email_group_id",
  3.   "_version" : 1,
  4.   "_seq_no" : 9,
  5.   "_primary_term" : 2,
  6.   "email_group" : {
  7.     "schema_version" : 2,
  8.     "name" : "example_email_group",
  9.     "emails" : [
  10.       {
  11.         "email" : "example@email.com"
  12.       }
  13.     ]
  14.   }
  15. }

copy

Update email group

When updating an email group, you can optionally include seq_no and primary_term as parameters. If these numbers don’t match the existing email group or the email group doesn’t exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response).

Example request

  1. PUT _plugins/_alerting/destinations/email_groups/<email_group_id>
  2. {
  3.   "name": "example_email_group",
  4.   "emails": [{
  5.     "email": "example@email.com"
  6.   }]
  7. }
  9. PUT _plugins/_alerting/destinations/email_groups/<email_group_id>?if_seq_no=16&if_primary_term=2
  10. {
  11.   "name": "example_email_group",
  12.   "emails": [{
  13.     "email": "example@email.com"
  14.   }]
  15. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "email_group_id",
  3.   "_version" : 4,
  4.   "_seq_no" : 17,
  5.   "_primary_term" : 2,
  6.   "email_group" : {
  7.     "schema_version" : 2,
  8.     "name" : "example_email_group",
  9.     "emails" : [
  10.       {
  11.         "email" : "example@email.com"
  12.       }
  13.     ]
  14.   }
  15. }

copy

Get email group

Retrieve the details of a specific email group destination using the following request, passing the ID of the email group you want to fetch.

Example request

  1. GET _plugins/_alerting/destinations/email_groups/<email_group_id>
  2. {
  3.   "name": "example_email_group",
  4.   "emails": [{
  5.     "email": "example@email.com"
  6.   }]
  7. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id" : "email_group_id",
  3.   "_version" : 4,
  4.   "_seq_no" : 17,
  5.   "_primary_term" : 2,
  6.   "email_group" : {
  7.     "schema_version" : 2,
  8.     "name" : "example_email_group",
  9.     "emails" : [
  10.       {
  11.         "email" : "example@email.com"
  12.       }
  13.     ]
  14.   }
  15. }

copy

Delete email group

Remove an existing email group from the list of destinations for alerts using the following request.

Example request

  1. DELETE _plugins/_alerting/destinations/email_groups/<email_group_id>

copy

Select to expand example response

Example response

  1. {
  2.   "_index" : ".opendistro-alerting-config",
  3.   "_type" : "_doc",
  4.   "_id" : "email_group_id",
  5.   "_version" : 1,
  6.   "result" : "deleted",
  7.   "forced_refresh" : true,
  8.   "_shards" : {
  9.     "total" : 2,
  10.     "successful" : 2,
  11.     "failed" : 0
  12.   },
  13.   "_seq_no" : 11,
  14.   "_primary_term" : 2
  15. }

copy

Search email group

Query and retrieve information about existing email groups used for alerting purposes, enabling you to filter and sort the results based on various criteria. An example is shown in the following request.

Example request

  1. POST _plugins/_alerting/destinations/email_groups/_search
  2. {
  3.   "from": 0,
  4.   "size": 20,
  5.   "sort": { "email_group.name.keyword": "desc" },
  6.   "query": {
  7.     "bool": {
  8.       "must": {
  9.         "match_all": {}
  10.       }
  11.     }
  12.   }
  13. }

copy

Select to expand example response

Example response

  1. {
  2.   "took" : 7,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 5,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : null,
  16.     "hits" : [
  17.       {
  18.         "_index" : ".opendistro-alerting-config",
  19.         "_type" : "_doc",
  20.         "_id" : "email_group_id",
  21.         "_seq_no" : 10,
  22.         "_primary_term" : 2,
  23.         "_score" : null,
  24.         "_source" : {
  25.           "schema_version" : 2,
  26.           "name" : "example_email_group",
  27.           "emails" : [
  28.             {
  29.               "email" : "example@email.com"
  30.             }
  31.           ]
  32.         },
  33.         "sort" : [
  34.           "example_email_group"
  35.         ]
  36.       },
  37.       ...
  38.     ]
  39.   }
  40. }

copy

Create comment

This is an experimental feature and is not recommended for use in a production environment.

Add comments to a specific alert, providing additional context or notes related to that alert, using the following request.

Example request

  1. POST _plugins/_alerting/comments/<alert-id>
  2. {
  3.   "content": "sample comment"
  4. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "0U6aBJABVWc3FrmWer9s",
  3.   "_seq_no": 7,
  4.   "_primary_term": 2,
  5.   "comment": {
  6.     "entity_id": "vCZkA5ABWTh3kzuBEL_9",
  7.     "entity_type": "alert",
  8.     "content": "sample comment",
  9.     "created_time": 1718064151148,
  10.     "last_updated_time": null,
  11.     "user": "admin"
  12.   }
  13. }

copy

Update comment

This is an experimental feature and is not recommended for use in a production environment.

Modify the content of a previously added comment associated with an alert using the following request.

Example request

  1. PUT _plugins/_alerting/comments/<comment-id>
  2. {
  3.   "content": "sample updated comment"
  4. }

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "0U6aBJABVWc3FrmWer9s",
  3.   "_seq_no": 8,
  4.   "_primary_term": 3,
  5.   "comment": {
  6.     "entity_id": "vCZkA5ABWTh3kzuBEL_9",
  7.     "entity_type": "alert",
  8.     "content": "sample updated comment",
  9.     "created_time": 1718064151148,
  10.     "last_updated_time": 1718064745485,
  11.     "user": "admin"
  12.   }
  13. }

copy

Search comment

This is an experimental feature and is not recommended for use in a production environment.

Query and retrieve existing comments associated with alerts using the following request.

Example request

  1. GET _plugins/_alerting/comments/_search
  2. {
  3.   "query": {
  4.     "match_all" : {}
  5.   }
  6. }

copy

Select to expand example response

Example response

  1. {
  2.   "took": 14,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 2,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1,
  16.     "hits": [
  17.       {
  18.         "_index": ".opensearch-alerting-comments-history-2024.06.10-1",
  19.         "_id": "xE5tBJABVWc3FrmWRL5i",
  20.         "_version": 1,
  21.         "_seq_no": 3,
  22.         "_primary_term": 2,
  23.         "_score": 1,
  24.         "_source": {
  25.           "entity_id": "vCZkA5ABWTh3kzuBEL_9",
  26.           "entity_type": "alert",
  27.           "content": "a different sample comment",
  28.           "created_time": 1718061188191,
  29.           "last_updated_time": null,
  30.           "user": "admin"
  31.         }
  32.       },
  33.       {
  34.         "_index": ".opensearch-alerting-comments-history-2024.06.10-1",
  35.         "_id": "0U6aBJABVWc3FrmWer9s",
  36.         "_version": 3,
  37.         "_seq_no": 9,
  38.         "_primary_term": 3,
  39.         "_score": 1,
  40.         "_source": {
  41.           "entity_id": "vCZkA5ABWTh3kzuBEL_9",
  42.           "entity_type": "alert",
  43.           "content": "sample updated comment",
  44.           "created_time": 1718064151148,
  45.           "last_updated_time": 1718064745485,
  46.           "user": "admin"
  47.         }
  48.       }
  49.     ]
  50.   }
  51. }

copy

Delete comment

This is an experimental feature and is not recommended for use in a production environment.

Remove a specific comment associated with an alert using the following request.

Example request

  1. DELETE _plugins/_alerting/comments/<comment-id>

copy

Select to expand example response

Example response

  1. {
  2.   "_id": "0U6aBJABVWc3FrmWer9s"
  3. }

copy