---
title: Monitor API Options
description: >-
  Comprehensive reference for monitor API configuration options including common
  settings, permissions, anomaly alerts, and metric alerts.
breadcrumbs: Docs > Monitors > Monitor Guides > Monitor API Options
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Monitor API Options

This guide describes the options available when configuring monitors through the [Monitors API](https://docs.datadoghq.com/api/latest/monitors.md). 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{% #common-options %}

{% dl %}

{% dt %}
`silenced`
{% /dt %}

{% dd %}
**Deprecated**: Reflects v1 downtimes only. Use the [Downtimes API](https://docs.datadoghq.com/api/latest/downtimes.md) 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.
{% /dd %}

{% dt %}
`new_host_delay`
{% /dt %}

{% dd %}
**Deprecated**: Use `new_group_delay` instead. **Default**: `300` Time (in seconds) to allow a host to boot before evaluating monitor results.
{% /dd %}

{% dt %}
`new_group_delay`
{% /dt %}

{% dd %}
**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.
{% /dd %}

{% dt %}
`notify_no_data`
{% /dt %}

{% dd %}
**Default**: `false` A Boolean indicating whether the monitor notifies when data stops reporting.
{% /dd %}

{% dt %}
`no_data_timeframe`
{% /dt %}

{% dd %}
**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.
{% /dd %}

{% dt %}
`timeout_h`
{% /dt %}

{% dd %}
**Default**: `null` Hours without data before the monitor auto-resolves from a triggered state. Range: 0-24.
{% /dd %}

{% dt %}
`renotify_interval`
{% /dt %}

{% dd %}
**Default**: `null` Minutes after the last notification before the monitor re-notifies, if unresolved.
{% /dd %}

{% dt %}
`renotify_statuses`
{% /dt %}

{% dd %}
**Default**: `null` Statuses that trigger re-notification. Defaults to `alert` and `no data` when `renotify_interval` is set.
{% /dd %}

{% dt %}
`renotify_occurrences`
{% /dt %}

{% dd %}
**Default**: `null` Number of re-notifications to send at the `renotify_interval`. Requires `renotify_interval`.
{% /dd %}

{% dt %}
`escalation_message`
{% /dt %}

{% dd %}
**Default**: `null` Message to include with a re-notification. Supports `@username`. Requires `renotify_interval`.
{% /dd %}

{% dt %}
`notify_audit`
{% /dt %}

{% dd %}
**Default**: `false` A Boolean indicating whether tagged users are notified of changes to the monitor.
{% /dd %}

{% dt %}
`notify_by`
{% /dt %}

{% dd %}
**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.
{% /dd %}

{% dt %}
`notification_preset_name`
{% /dt %}

{% dd %}
**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`.
{% /dd %}

{% dt %}
`include_tags`
{% /dt %}

{% dd %}
**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`.
{% /dd %}

{% dt %}
`evaluation_delay`
{% /dt %}

{% dd %}
**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.
{% /dd %}

{% /dl %}

## Permissions options{% #permissions-options %}

{% dl %}

{% dt %}
`restricted_roles`
{% /dt %}

{% dd %}
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](https://docs.datadoghq.com/api/latest/roles.md).
{% /dd %}

{% /dl %}

**Note**: You can also set up permissions on monitors based on [Teams](https://docs.datadoghq.com/account_management/teams.md) and users, in addition to roles, with [Restriction Policies](https://docs.datadoghq.com/api/latest/restriction-policies.md). For more information on restricting permissions for monitors, see the [dedicated guide](https://docs.datadoghq.com/monitors/guide/how-to-set-up-rbac-for-monitors.md).

## Options by monitor type{% #options-by-monitor-type %}

{% collapsible-section %}
### Anomaly options

*These options only apply to anomaly monitors and are ignored for other monitor types.*

{% dl %}

{% dt %}
`threshold_windows`
{% /dt %}

{% dd %}
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'}}`
{% /dd %}

{% /dl %}

{% /collapsible-section %}

{% collapsible-section %}
### Metric alert options

*These options only apply to metric alerts.*

{% dl %}

{% dt %}
`thresholds`
{% /dt %}

{% dd %}
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](https://docs.datadoghq.com/monitors/guide/recovery-thresholds.md) for your monitor, use the attributes `critical_recovery` and `warning_recovery`.
**Example**: `{'critical': 90, 'warning': 80, 'critical_recovery': 70, 'warning_recovery': 50}`
{% /dd %}

{% dt %}
`require_full_window`
{% /dt %}

{% dd %}
**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.
{% /dd %}

{% /dl %}

{% /collapsible-section %}

{% collapsible-section %}
### Service check options

*These options only apply to service checks and are ignored for other monitor types.*

{% dl %}

{% dt %}
`thresholds`
{% /dt %}

{% dd %}
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}`
{% /dd %}

{% /dl %}

{% /collapsible-section %}

{% collapsible-section %}
### Logs alert options

*These options only apply to logs alerts.*

{% dl %}

{% dt %}
`thresholds`
{% /dt %}

{% dd %}
A dictionary of thresholds by status.
**Example**: `{'ok': 1, 'critical': 1, 'warning': 1}`
{% /dd %}

{% dt %}
`aggregation`
{% /dt %}

{% dd %}
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.

{% /dd %}

{% dt %}
`enable_logs_sample`
{% /dt %}

{% dd %}
**Default**: `false` A Boolean to add samples or values to the notification message.
{% /dd %}

{% /dl %}

{% /collapsible-section %}

{% collapsible-section %}
### Synthetic test monitor options

*These options only apply to Synthetic test monitors.*

{% dl %}

{% dt %}
`min_failure_duration`
{% /dt %}

{% dd %}
**Default**: `0` How long, in seconds, a test must be in failure before alerting. Maximum: `7200`.
{% /dd %}

{% dt %}
`min_location_failed`
{% /dt %}

{% dd %}
**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.
{% /dd %}

{% /dl %}

{% /collapsible-section %}

{% collapsible-section %}
### Options for APM Trace Analytics, Audit Trail, CI, Error Tracking, Event, Logs, and RUM monitors

*These options only apply to the monitor types listed in this section's title.*

{% dl %}

{% dt %}
`group_retention_duration`
{% /dt %}

{% dd %}
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`.
{% /dd %}

{% dt %}
`on_missing_data`
{% /dt %}

{% dd %}
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`.
{% /dd %}

{% dt %}
`enable_samples`
{% /dt %}

{% dd %}
A Boolean to send a list of samples when the monitor triggers. Only available for CI Test and CI Pipeline monitors.
{% /dd %}

{% /dl %}

{% /collapsible-section %}