monitors

Manage Datadog monitors. Actions: list, get, search, create, update, delete, mute, unmute, top, history, preview, test_notification. Filters: name, tags, groupStates (alert/warn/ok/no data). get/create/update return the full options object so callers can safely read-then-patch.

create/update accept a config object validated against a typed schema covering the documented Datadog Monitor fields:

• Top-level: name, type, query, message, tags, priority (1-5, nullable), restrictedRoles, multi, options.

• options.* validated keys grouped by category:

  • notification: notifyNoData, noDataTimeframe, notifyAudit, notificationPresetName.

  • evaluation/delay: newHostDelay, newGroupDelay, evaluationDelay, requireFullWindow, onMissingData.

  • renotification: renotifyInterval (nullable), renotifyOccurrences, renotifyStatuses, escalationMessage.

  • lifecycle: timeoutH (nullable), includeTags, locked, silenced (record of timestamps/null), groupRetentionDuration.

  • thresholds: thresholds (critical/warning/ok/criticalRecovery/warningRecovery/unknown), thresholdWindows.

  • scheduling: schedulingOptions. Unknown keys (top-level or under options) are forwarded to Datadog as-is and surfaced via an optional warnings array on the response, so the schema does not lag the API. snake_case aliases are accepted on input and normalized to camelCase before validation. Validation errors short-circuit before any HTTP call and surface as 'EINVALID_MONITOR_CONFIG: : '. Reference: https://docs.datadoghq.com/api/latest/monitors/

top: Ranked monitors by alert frequency with real monitor names and context breakdown.

• Returns: {rank, monitor_id, name (with {{template.vars}}), message (template), total_count, by_context}

• Perfect for weekly/daily alert reports

• Gets real monitor names from monitors API (not event titles)

• WARNING: total_count is the raw alert-event count and INCLUDES renotifies/re-evaluations. For monitors stuck in Alert state, Datadog emits a renotify event every renotify_interval minutes, which inflates this count well beyond the number of real fires. When the question is "how many times did this monitor actually fire", use action=history instead.

history: Count and list real state transitions for one monitor over a time window.

• Inputs: id (required, monitor ID), from/to (optional time range), transitionType (optional filter, defaults to ["alert","alert recovery"]), group (optional multi-alert group filter).

• Returns: {transitions: [{timestamp, monitorId, monitorName, group, fromState, toState, transitionType, eventId}], count, meta}

• count = transitions.length — the number of REAL state changes (fires + recoveries by default), NOT the renotify-inflated count returned by action=top or events action=search.

• Backed by Datadog v2 events search with a hardcoded source:alert + @monitor.transition. transition_type filter that excludes renotifies by default. To include renotifies, pass transitionType including "renotify".

preview: Render a Datadog monitor message template against a context (read-only safe).

• Inputs: either inline 'message' OR 'monitor_id' (or existing 'id'); plus optional 'context' { variables, conditionals }.

• Supported syntax: {{variable.name}} substitution and conditional blocks {{#name}}...{{/name}} / {{^name}}...{{/name}} where name is one of: is_alert, is_warning, is_no_data, is_recovery, is_alert_to_warning, is_warning_to_alert.

• Missing variables render as {{undefined:name}} markers and are reported in 'variablesMissing'.

• Loops ({{#each ...}}) and partials ({{> ...}}) return EUNSUPPORTED_TEMPLATE_SYNTAX.

• Allowed under --read-only (no mutation; at most a getMonitor load).

test_notification: KNOWN LIMITATION — always returns ENOT_SUPPORTED.

• Datadog's public REST API exposes no monitor test-notification endpoint at v1 or v2 (audited against the official OpenAPI specs). The v1 SDK has no notifyMonitor / testMonitor method.

• Allowed under --read-only because no Datadog HTTP call is attempted.

• If Datadog publishes such an endpoint in future, this action will be reimplemented to invoke it.

• Workaround: use the 'Test Notifications' button in the Datadog monitor UI.

For generic event grouping (deployments, configs), use events tool instead. Note that the events tool's action=search with source:alert ALSO includes renotifies; use its transitionType filter (or this action=history) for fires-only counts.