--- title: Alerts conditions API field names source: https://docs.newrelic.com/docs/alerts/scale-automate/rest-api/alerts-conditions-api-field-names --- The [REST API endpoints](https://docs.newrelic.com/docs/alerts/new-relic-alerts-beta/getting-started/rest-api-calls-new-relic-alerts) allow you to create conditions for your policies. This glossary contains the names and descriptions of each of the fields that you can use to define or update a condition. ## Before using the REST API [#before-start] The REST API is no longer the preferred way to programmatically manage your alerts. For more context, read the [Intro to APIs for alerts](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/advanced-alerts/alerts-api/intro-alerts-api). ## Required and optional fields [#required] The API includes four types of alerts conditions: - APM - External services - NRQL - Synthetic monitoring All of the fields used with a specific condition type are required except for these optional fields: - `enabled` (defaults to `false`) - `runbook_url` - `user_defined` ## Field definitions [#field-names] Not every field listed in this glossary is required for every condition type. The condition type for which a field must be used is listed in each description. **condition_scope** This field allows you to scope a condition to either a JVM instance or to a whole application. This may be one of the strings: - instance - application Used for: - Conditions - Entity conditions For instance-based and JVM health metrics, see also [`violation_close_timer`](#violation_close_timer). **enabled** This is the status of your alert condition and is optional. The default is `false`. This field may be used to enable or disable a condition for maintenance or testing periods. Used for: - Conditions - External service conditions - NRQL conditions - Synthetic monitoring conditions **entities** This is an array of [entity](https://docs.newrelic.com/docs/alerts/new-relic-alerts/getting-started/alerts-glossary#alert-entity) IDs identifying the objects that will be monitored with your condition. These may be application IDs, browser IDs, key transaction IDs, external service IDs, etc. These are entered as a series of comma-separated integers if there is more than one. Used for: - Conditions - External service conditions **expiration\[expiration_duration]** How long to wait, in seconds, after the last data point is received by our platform before considering the signal as lost. This is based on the time when data arrives and not on data timestamps. The default is null. Add a value to enable loss of signal detection. Used for: - NRQL conditions **expiration\[close_violations_on_expiration]** When `true`, this closes all currently open incidents when no signal is heard within the `expiration_duration` time. The default is `false`. Used for: - NRQL conditions **expiration\[open_violation_on_expiration]** When true, this opens a loss of signal incident when there is no signal within the `expiration_duration` time. The default is `false`. Used for: - NRQL conditions **external_service_url** This is the URL of the external service to be monitored. This string must **not** include the protocol. For example, use `example.com`, not `https://example.com`. Used for: - External service conditions **metric** The **metric** field is used for three alert categories. The exact parameters available for use depend on the setting in the [type](#type) field. These are listed below according to their alert [type](#type) field. **Alerts conditions** The value specified in the [type](#type) field controls which of the parameters may be specified. The [type](#type) field and corresponding available **parameter** names are listed in the following table. Only one may be specified. | `type` | Parameter | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apm_app_metric | - apdex - error_percentage - response_time_web - response_time_background - throughput_web - throughput_background - user_defined | | apm_kt_metric | - apdex - error_percentage - error_count - response_time - throughput | | browser_metric | - end_user_apdex - total_page_load - page_rendering - web_application - network - dom_processing - request_queuing - ajax_response_time - page_views_with_js_errors - page_view_throughput - ajax_throughput - user_defined | | browser_metric_baseline | - page_view_throughput - average_response_time - ajax_response_time - ajax_application_time | | mobile_metric | - database - images - json, network - view_loading - network_error_percentage - status_error_percentage - user_defined | **Alerts external service conditions** The value specified in the [type](#type) field controls which of the parameters may be specified. The [type](#type) field and corresponding available **parameter** names are listed in the following table. Only one may be specified. | `type` | Parameter | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apm_external_service | - apdex - error_percentage - response_time_web - response_time_background - throughput_web - throughput_background - user_defined | | apm_app_metric_baseline | - external_service_transaction_time - error_count - database_transaction_time - throughput_web - response_time_web - non_web_transaction_time - web_transaction_database_time - non_web_transaction_database_time | | mobile_external_service | - response_time_average - response_time_minimum - response_time_maximum - throughput - network_failure_percentage - http_status_error_percentage | **monitor_id** This is the GUID of the Synthetic monitoring to alert on. Used for: - Synthetic monitoring conditions **name** This condition title will allow to you identify it in the UI. Follow the [guidelines](https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/alert-conditions/#name-your-condition) for making this descriptive but short. Used for: - Conditions - External service conditions - NRQL conditions - Synthetic monitoring conditions **nrql\[query]** This is the NRQL query that alerts monitors as part of a NRQL condition. Used for: - NRQL conditions **nrql\[since_value]** Deprecated in favor of an `aggregation_method` with either an `aggregation_delay` or `aggregation_timer`. This is the timeframe (in minutes) in which to evaluate the specified NRQL query. `since_value` must be between `1` and `20`. Used for: - NRQL conditions **runbook_url** The [runbook](https://docs.newrelic.com/docs/alerts/new-relic-alerts/getting-started/alerts-glossary#alert-runbook) URL to display in notifications. This field is optional. Used for: - Conditions - External service conditions - NRQL conditions - Synthetic monitoring conditions **signal\[aggregation_delay]** The length of time in seconds to wait for the aggregation window to fill with data. Required when using CADENCE or EVENT_FLOW `aggregation_method` types. Default is **120 seconds**. Used with event flow and cadence aggregation methods. Used for: - NRQL conditions **signal\[aggregation_method]** New Relic aggregates data into windows, and needs to determine when the current window ends and the next one begins. The `aggregation_method` is the logic that tells us when we have all the data for a given aggregation window. Once the window is closed, the data is aggregated into a single point and evaluated against the threshold. This field is optional. One of the following three values can be specified: - `EVENT_FLOW`: (Default) Each aggregation window will wait until it starts to see timestamps arrive that are past its own delay setting. Once this occurs, the data is published. Relies on the timestamps of arriving data, so wall-clock time is no longer relevant. Works best for sources that come in frequently and with low event spread (high througput metrics). - `CADENCE`: Classic New Relic logic where each evaluation window waits exactly as long as the `aggregation_delay` setting, using the wall-clock time as a timer. `aggregation_delay` is required when using this option. Data arriving too late will be dropped, which can cause false alerts. - `EVENT_TIMER`: Each aggregation window has a timer on it, set to the `aggregation_timer` value. The timer starts running as soon as the first data point appears for that aggregation window (based on the data point’s timestamp). The `aggregation_timer` is reset for each new data point that arrives for that window. Once the `aggregation_timer` reaches 0, the aggregation window is published. Ideal for sparse and batched data, such as cloud integrations and infrequent error logs. The default is **Event flow**. Used for: - NRQL conditions **signal\[aggregation_timer]** The length of time in seconds to wait after each data point is received, to ensure the entire batch is processed. Required when using the `EVENT_TIMER` `aggregation_method` type. Default is **60 seconds**. Used for: - NRQL conditions **signal\[aggregation_window]** Streaming alerts gather data together into specific amounts of time before running the function in the NRQL query. These windows of time are customizable. Data points are collected together based on their timestamps and reported as a batch. The customizable aggregation window provides greater flexibility and fewer false incidents when alerting on irregular or less frequent data points. In the UI, under **Advanced signal settings**, this is the **Aggregation window** field. Default is **60 seconds**. Maximum is 6 hours. Used for: - NRQL conditions **signal\[slide_by]** By default, aggregation windows are grouped sequentially. This can lead to spiky charts whenever one window starts and another begins. Use `slide_by` to create sliding windows. Sliding aggregated windows overlap, creating smoother charts. The `slide_by` interval sets the duration of the overlap. In the UI, under **Advanced signal settings**, click the **Use sliding window aggregation** toggle to enable sliding windows. Default is based on the current window duration. The `slide_by` interval must divide evenly into your aggregation window duration. The `slide_by` interval must also be less than the window duration. **signal\[evaluation_offset]** Deprecated in favor of an `aggregation_method` with either an `aggregation_delay` or `aggregation_timer`. The offset is how long we wait for late data before evaluating each aggregation window. Waiting longer gives a more accurate signal but increases latency. The default is **3 aggregation windows**. Used for: - NRQL conditions **signal\[fill_option]** For sporadic data, you can avoid false alerts by filling the gaps (empty windows) with synthetic data. - `none`: (Default) Use this if you don't want to take any action on empty aggregation windows. On evaluation, an empty aggregation window will reset the threshold duration timer. For example, if a condition says that all aggregation windows must have data points above the threshold for 5 minutes, and 1 of the 5 aggregation windows is empty, then the condition won't open an incident. - `static`: Use this if you'd like to insert a custom static value into the empty aggregation windows before they're evaluated. This option has an additional, required parameter of `fillValue` that specifies what static value should be used. This defaults to 0. - `last_value`: Use this to insert the last seen value before evaluation occurs. We maintain the state of the last seen value for 2 hours. In the UI, under **Advanced signal settings**, this is the **Fill data gaps with** field. Used for: - NRQL conditions **signal\[fill_value]** This is the value used by the `fill_option` custom value. The default is `0`. Used for: - NRQL conditions **terms\[duration]** This is the time (in minutes) for the condition to persist before triggering an event. It corresponds to the duration set when [adding a threshold](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/define-thresholds-trigger-alert#adding-thresholds) in the UI. Used for: - Conditions - NRQL conditions **terms\[exclude_from_entity_status]** This field allows you to control the impact of an alert condition on the [health status](https://docs.newrelic.com/docs/alerts/create-alert/examples/view-entity-health-status-find-entities-without-alert-conditions) of the associated entity. To ensure that the associated entity's health status remains unchanged, even when alert incidents are triggered, set it to `true`. It corresponds to the **Do not report system health status** toggle when [setting thresholds for alert conditions](https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/alert-conditions/#disable-health-status-reporting) in the UI. **terms\[operator]** This determines what comparison will be used between the **value_function** and the **terms\[threshold]** value to trigger an event. It corresponds to the operation selected when [adding a threshold](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/define-thresholds-trigger-alert#adding-thresholds) in the UI. It must be one of the following strings: - above - above_or_equals (NRQL conditions only) - below - below_or_equals (NRQL conditions only) - equal - not_equals (NRQL conditions only) Used for: - Conditions - External service conditions - NRQL conditions **terms\[priority]** This corresponds to the [severity level](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/define-thresholds-trigger-alert#threshold-levels) selected when setting the threshold values for the condition in the UI. This must be one of the following strings: - critical - warning Used for: - Conditions - External service conditions - NRQL conditions **terms\[threshold]** This is the threshold that the **value_function** must be compared to using the **terms\[operator]** for an event to be triggered. It corresponds to the numeric value specified in the UI when [adding the threshold values](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/define-thresholds-trigger-alert#adding-thresholds). This is a numeric value and must be 0 (zero) or greater. Used for: - Conditions - External service conditions - NRQL conditions **terms\[time_function]** This corresponds to the settings made in the UI when [adding the threshold values](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/define-thresholds-trigger-alert#adding-thresholds). The choices are: - all (corresponding to `for at least` in the UI) - any (corresponding to `at least once in` in the UI) Used for: - Conditions - External service conditions - NRQL conditions **type** This defines the type of metric that will be used for the alert. Allowable content for the [metric](#metric) field depends on the **type** value chosen. There are two [product categories](https://docs.newrelic.com/docs/alerts/new-relic-alerts/configuring-alert-policies/select-product-targets-alert-condition) : **Alerts conditions** For this category, **type** is set to one of the following strings indicating the type of [alerts condition](#alerts_conditions). | `type` | Use | | ----------------------- | -------------------------------------------------------------------------- | | apm_app_metric | APM application metric will trigger an alert. | | apm_app_metric_baseline | APM application metric will trigger an alert (using an anomaly threshold). | | apm_kt_metric | APM key transaction metric will trigger an alert. | | browser_metric | Browser metric will trigger an alert. | | browser_metric_baseline | Browser metric will trigger an alert (using an anomaly threshold). | | mobile_metric | Mobile metric will trigger an alert. | Used for: - Conditions **Alerts external service conditions** For this category, **type** is set to one of the following strings indicating the type of [external service condition](#alerts_external_service_conditions). | `type` | Use | | ----------------------- | --------------------------------------------- | | apm_external_service | APM external metric will trigger an alert. | | mobile_external_service | Mobile external metric will trigger an alert. | Used for: - External service conditions **user_defined\[metric] (optional)** This is the name of a user defined custom **metric** to be used to determine if an event should be triggered. The **user_defined\[value_function]** associated with the metric is compared with the **terms\[threshold]** value when evaluating if an incident should be triggered. The comparison is performed using the operator defined by **terms\[operator]**. Used for: - Conditions - External service conditions - Synthetic monitoring conditions **user_defined\[value_function] (optional)** This is the numeric value obtained from the custom metric specified by **user_defined\[metric]**. It is compared with the **terms\[threshold]** value when evaluating if an incident should be triggered. The comparison is performed using the operator defined by **terms\[operator]**. One of these value functions must be specified: - average - min - max - total - sample_size Used for: - Conditions **value_function** When used for a [NRQL condition](https://docs.newrelic.com/docs/alerts/rest-api-alerts/new-relic-alerts-rest-api/rest-api-calls-new-relic-alerts#nrql-condition), the options are: - single_value (condition is evaluated based on each query's returned value) - sum (condition is evaluated based on the sum of each query's returned values over the specified duration) **violation_time_limit_seconds** Use to automatically close instance-based incidents after the number of seconds specified. Default is **259,200 seconds** (3 days). Maximum is 30 days. Used for: - Location conditions - NRQL conditions **violation_close_timer** Use to automatically close instance-based incidents, including JVM health metric incidents, after the number of hours specified. Must be between 1 and 720 hours. Defaults to 72 hours. Used for: - `apm_app_metric` (with `condition_scope` set to `instance`) - `apm_jvm_metric`