This guide describes the options available when configuring monitors through the Monitors API. It covers options that:
- Are common to all monitor types.
- Control edit permissions.
- Only apply to specific monitor types, such as metric, anomaly, log, service check, and Synthetic test monitors.
Common options
silenced- Deprecated: Reflects v1 downtimes only. Use the Downtimes API instead.
Default: null
Dictionary of scopes to timestamps, or null to mute forever.Example: {'*': null} mutes everything; {'role:db': 1412798116} mutes role:db until that timestamp.
new_host_delay- Deprecated: Use
new_group_delay instead.
Default: 300
Time (in seconds) to allow a host to boot before evaluating monitor results. new_group_delay- Default:
60
Time (in seconds) before alerting on new groups, so new applications or containers have time to start. Non-negative integer. Prevents alerts on newly created group-by values, such as containers that spike CPU on startup. notify_no_data- Default:
false
A Boolean indicating whether the monitor notifies when data stops reporting. no_data_timeframe- Default:
null
Minutes before the monitor notifies after data stops reporting.
Recommended: 2x the monitor time frame for query alerts, or 2 minutes for service checks. timeout_h- Default:
null
Hours without data before the monitor auto-resolves from a triggered state.
Range: 0-24. renotify_interval- Default:
null
Minutes after the last notification before the monitor re-notifies, if unresolved. renotify_statuses- Default:
null
Statuses that trigger re-notification. Defaults to alert and no data when renotify_interval is set. renotify_occurrences- Default:
null
Number of re-notifications to send at the renotify_interval.
Requires renotify_interval. escalation_message- Default:
null
Message to include with a re-notification. Supports @username.
Requires renotify_interval. notify_audit- Default:
false
A Boolean indicating whether tagged users are notified of changes to the monitor. notify_by- Default:
null
Tags that control alert granularity for grouped monitors. Must be a subset of the query’s group-by tags. Set to ["*"] to notify as a simple alert. notification_preset_name- Default:
show_all
Controls how much extra content, such as the query or notified handles, appears in the notification. One of show_all, hide_query, hide_handles, hide_all, hide_query_and_handles, show_only_snapshot, hide_handles_and_footer. include_tags- Default:
true
A Boolean indicating whether notifications include the triggering tags in the title.
Example: true results in [Triggered on {host:h1}] Monitor Title; false results in [Triggered] Monitor Title. evaluation_delay- Default:
null
Time (in seconds) to delay evaluation. Useful for backfilled data sources, such as AWS CloudWatch. Available on most monitor types; not supported on SLO monitors outside of burn rate alerts.
Permissions options
restricted_roles- An array listing the UUIDs of the roles allowed to edit the monitor. Monitor editing includes updates to the monitor configuration, deleting the monitor, and muting the monitor for any amount of time. Pull role UUIDs from the Roles API.
Note: You can also set up permissions on monitors based on Teams and users, in addition to roles, with Restriction Policies. For more information on restricting permissions for monitors, see the dedicated guide.
Options by monitor type
These options only apply to anomaly monitors and are ignored for other monitor types.
threshold_windows- A dictionary containing
recovery_window and trigger_window.recovery_window: How long an anomalous metric must be normal before the alert recovers.trigger_window: How long a metric must be anomalous before an alert triggers.
Example: {'threshold_windows': {'recovery_window': 'last_15m', 'trigger_window': 'last_15m'}}
These options only apply to metric alerts.
thresholds- A dictionary of thresholds by threshold type. There are two threshold types for metric alerts: critical and warning. Critical is defined in the query, but can also be specified in this option. Warning threshold can only be specified using the thresholds option. If you want to use recovery thresholds for your monitor, use the attributes
critical_recovery and warning_recovery.Example: {'critical': 90, 'warning': 80, 'critical_recovery': 70, 'warning_recovery': 50}
require_full_window- Default:
false
A Boolean indicating whether this monitor needs a full window of data before it’s evaluated. Datadog recommends you set this to false for sparse metrics; otherwise some evaluations are skipped.
These options only apply to service checks and are ignored for other monitor types.
thresholds- A dictionary of thresholds by status. Because service checks can have multiple thresholds, they aren’t defined directly in the query.
Example: {'ok': 1, 'critical': 1, 'warning': 1}
These options only apply to logs alerts.
thresholds- A dictionary of thresholds by status.
Example: {'ok': 1, 'critical': 1, 'warning': 1}
aggregation- A dictionary of
type, metric, and groupBy.Example: {"metric": "count","type": "count","groupBy": "core_service"}
type: Three types are supported: count, cardinality, and avg.metric: For cardinality, use the name of the facet. For avg, use the name of the metric. For count, put count as metric.groupBy: Name of the facet on which you want to group by.
enable_logs_sample- Default:
false
A Boolean to add samples or values to the notification message.
These options only apply to Synthetic test monitors.
min_failure_duration- Default:
0
How long, in seconds, a test must be in failure before alerting. Maximum: 7200. min_location_failed- Default:
1
The minimum number of test locations that must be in failure at the same time during the min_failure_duration window before alerting. Used with min_failure_duration as part of the advanced alerting rules.
These options only apply to the monitor types listed in this section’s title.
group_retention_duration- The time span after which groups with missing data is dropped from the monitor state. Minimum: one hour. Maximum: 72 hours.
Example values: 60m, 1h, 2d.
on_missing_data- Controls how groups or monitors behave when an evaluation returns no datapoints. The default behavior depends on the query type: monitors using a count query treat an empty evaluation as
0 and compare it to the threshold conditions, and monitors using another query type, such as gauge, measure, or rate, show the last known status. One of default, show_no_data, show_and_notify_no_data, or resolve. enable_samples- A Boolean to send a list of samples when the monitor triggers. Only available for CI Test and CI Pipeline monitors.
