openapi: 3.0.0
info:
contact:
email: support@datadoghq.com
name: Datadog Support
url: https://www.datadoghq.com/support/
description: The Datadog API is an HTTP REST API. The API uses resource-oriented URLs to call the API, uses status codes to indicate the success or failure of requests, returns JSON from all requests, and uses standard HTTP response codes. Use the Datadog API to access the Datadog platform programmatically.
title: Datadog Account Monitors API
version: '1.0'
servers:
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: The regional site for Datadog customers.
enum:
- datadoghq.com
- us3.datadoghq.com
- us5.datadoghq.com
- ap1.datadoghq.com
- datadoghq.eu
- ddog-gov.com
subdomain:
default: api
description: The subdomain where the API is deployed.
- url: '{protocol}://{name}'
variables:
name:
default: api.datadoghq.com
description: Full site DNS name.
protocol:
default: https
description: The protocol for accessing the API.
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: Any Datadog deployment.
subdomain:
default: api
description: The subdomain where the API is deployed.
security:
- apiKeyAuth: []
appKeyAuth: []
tags:
- name: Monitors
description: Create, read, update, and delete monitors
paths:
/api/v1/monitor:
post:
operationId: createMonitor
summary: Datadog Create a Monitor
description: Creates a new monitor with the specified configuration. The monitor type determines which query language and threshold options are available. Monitors can alert on metric thresholds, anomalies, log patterns, APM traces, synthetic test results, and more. Upon creation, Datadog begins evaluating the monitor against the defined query and will send notifications when alert conditions are met.
tags:
- Monitors
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Monitor'
responses:
'200':
description: Successfully created monitor
content:
application/json:
schema:
$ref: '#/components/schemas/Monitor'
'400':
description: Bad request - invalid monitor configuration
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'403':
description: Forbidden - insufficient permissions to create monitors
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
get:
operationId: listMonitors
summary: Datadog List All Monitors
description: Returns a paginated list of monitors for your Datadog organization. Results can be filtered by monitor type, group states, name tags, monitor tags, creator, and ID. Supports sorting by name, status, and type. Use this endpoint to audit your monitoring configuration or build monitoring dashboards.
tags:
- Monitors
parameters:
- name: group_states
in: query
required: false
description: Comma-separated list of group states to filter monitors by (alert, ignored, no data, ok, skipped, unknown, warn)
schema:
type: string
example: example_value
- name: name
in: query
required: false
description: Filter monitors by name substring match
schema:
type: string
example: Example Monitor
- name: tags
in: query
required: false
description: Comma-separated list of tags to filter monitors by
schema:
type: string
example: env:production
- name: monitor_tags
in: query
required: false
description: Comma-separated list of monitor-specific tags to filter by
schema:
type: string
example: env:production
- name: with_downtimes
in: query
required: false
description: When true, includes downtime information in the response
schema:
type: boolean
example: true
- name: id_offset
in: query
required: false
description: Monitor ID to start paginating from (for cursor-based pagination)
schema:
type: integer
example: 42
- name: page
in: query
required: false
description: The page number to retrieve (zero-indexed, for offset-based pagination)
schema:
type: integer
minimum: 0
example: 42
- name: page_size
in: query
required: false
description: The number of monitors to return per page (default 100, max 1000)
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
example: 42
responses:
'200':
description: Successful response with list of monitors
content:
application/json:
schema:
type: array
description: List of monitors matching the specified filters
items:
$ref: '#/components/schemas/Monitor'
'400':
description: Bad request - invalid filter parameters
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'403':
description: Forbidden - insufficient permissions to list monitors
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v1/monitor/{monitor_id}:
get:
operationId: getMonitor
summary: Datadog Get a Monitor
description: Returns the configuration and current status of a specific monitor identified by its ID. Includes the monitor query, notification settings, alert thresholds, and current group statuses. Optionally includes downtime and creator information.
tags:
- Monitors
parameters:
- $ref: '#/components/parameters/monitorIdParam'
- name: group_states
in: query
required: false
description: Comma-separated group states to include in the response (alert, ignored, no data, ok, skipped, unknown, warn)
schema:
type: string
example: example_value
- name: with_downtimes
in: query
required: false
description: When true, includes active downtime information in the response
schema:
type: boolean
example: true
responses:
'200':
description: Successful response with monitor details
content:
application/json:
schema:
$ref: '#/components/schemas/Monitor'
'400':
description: Bad request - invalid monitor ID format
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'403':
description: Forbidden - insufficient permissions to view this monitor
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'404':
description: Not found - monitor with the specified ID does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateMonitor
summary: Datadog Edit a Monitor
description: Updates the configuration of an existing monitor identified by its ID. The request body replaces the entire monitor configuration, so include all desired fields in the update. Changes to the query or thresholds take effect immediately. Updating notification channels or message templates applies to future alerts.
tags:
- Monitors
parameters:
- $ref: '#/components/parameters/monitorIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorUpdateRequest'
responses:
'200':
description: Successfully updated monitor
content:
application/json:
schema:
$ref: '#/components/schemas/Monitor'
'400':
description: Bad request - invalid monitor configuration or missing required fields
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'403':
description: Forbidden - insufficient permissions to update this monitor
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'404':
description: Not found - monitor with the specified ID does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteMonitor
summary: Datadog Delete a Monitor
description: Permanently deletes the monitor with the specified ID. Deletion cannot be undone. Active alerts and notifications for the monitor are immediately cancelled. Any associated SLOs referencing this monitor must be updated before the monitor can be deleted.
tags:
- Monitors
parameters:
- $ref: '#/components/parameters/monitorIdParam'
- name: force
in: query
required: false
description: When true, forcefully deletes the monitor even if it is referenced by SLOs or composite monitors
schema:
type: string
example: example_value
responses:
'200':
description: Successfully deleted monitor
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedMonitor'
'400':
description: Bad request - monitor cannot be deleted (e.g., referenced by SLO)
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'403':
description: Forbidden - insufficient permissions to delete this monitor
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'404':
description: Not found - monitor with the specified ID does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
MonitorUpdateRequest:
type: object
description: Request body for updating an existing monitor configuration
properties:
type:
type: string
description: The type of the monitor (changing type may reset other settings)
example: metric alert
query:
type: string
description: The updated monitor query expression
example: avg:system.cpu.user{*}
name:
type: string
description: The updated descriptive name for the monitor
example: Example Monitor
message:
type: string
description: The updated notification message body
example: CPU usage is high on {{host.name}}
tags:
type: array
description: The updated list of tags to associate with the monitor
items:
type: string
options:
$ref: '#/components/schemas/MonitorOptions'
priority:
type: integer
description: The updated priority level (1 highest to 5 lowest)
minimum: 1
maximum: 5
example: 42
APIErrorResponse:
type: object
description: Standard API error response returned for failed requests
required:
- errors
properties:
errors:
type: array
description: List of error messages describing the failure
items:
type: string
Creator:
type: object
description: Information about the user who created the monitor
properties:
id:
type: integer
description: The unique numeric ID of the creator user
example: 42
name:
type: string
description: The display name of the creator user
example: Example Monitor
email:
type: string
format: email
description: The email address of the creator user
example: user@example.com
handle:
type: string
description: The Datadog handle (username) of the creator user
example: example_value
MonitorThresholds:
type: object
description: Alert threshold values for metric and service check monitors
properties:
critical:
type: number
format: double
description: The threshold value that triggers a CRITICAL alert notification
example: 95.5
critical_recovery:
type: number
format: double
description: The threshold value at which a CRITICAL alert recovers to OK state
example: 95.5
warning:
type: number
format: double
description: The threshold value that triggers a WARNING alert notification
example: 95.5
warning_recovery:
type: number
format: double
description: The threshold value at which a WARNING alert recovers to OK state
example: 95.5
ok:
type: number
format: double
description: The threshold for service check monitors indicating an OK state (used with service check monitors)
example: 95.5
unknown:
type: number
format: double
description: The threshold for service check monitors indicating an UNKNOWN state
example: 95.5
DeletedMonitor:
type: object
description: Response returned after successfully deleting a monitor
properties:
deleted_monitor_id:
type: integer
format: int64
description: The ID of the monitor that was deleted
example: 42
MonitorState:
type: object
description: The current evaluation state of the monitor across all groups
properties:
groups:
type: object
description: Map of monitor group names to their current state information
additionalProperties:
$ref: '#/components/schemas/MonitorGroupState'
Monitor:
type: object
description: A Datadog monitor that watches a metric or check and alerts when thresholds are exceeded
required:
- type
- query
- name
- message
properties:
id:
type: integer
format: int64
description: The unique numeric identifier of the monitor, assigned by Datadog upon creation
example: 42
type:
type: string
description: The type of monitor that determines the query language and alerting behavior
enum:
- composite
- event alert
- log alert
- metric alert
- process alert
- query alert
- rum alert
- service check
- synthetics alert
- trace-analytics alert
- slo alert
- event-v2 alert
- audit alert
- ci-pipelines alert
- ci-tests alert
- error-tracking alert
- database-monitoring alert
- network-performance alert
example: composite
query:
type: string
description: The monitor query expression using Datadog's query language for the specified monitor type
example: avg:system.cpu.user{*}
name:
type: string
description: A descriptive name for the monitor used for identification in dashboards and notifications
example: Example Monitor
message:
type: string
description: The notification message body sent when the monitor triggers, supports template variables and @-mentions
example: CPU usage is high on {{host.name}}
tags:
type: array
description: List of tags to associate with the monitor for filtering and organization
items:
type: string
options:
$ref: '#/components/schemas/MonitorOptions'
priority:
type: integer
description: The monitor priority level from 1 (highest) to 5 (lowest), used for sorting and filtering
minimum: 1
maximum: 5
example: 42
state:
$ref: '#/components/schemas/MonitorState'
creator:
$ref: '#/components/schemas/Creator'
created:
type: string
format: date-time
description: ISO 8601 timestamp when the monitor was created
example: example_value
modified:
type: string
format: date-time
description: ISO 8601 timestamp when the monitor was last modified
example: example_value
deleted:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp when the monitor was deleted, or null if not deleted
example: example_value
restricted_roles:
type: array
description: List of role IDs whose members can edit this monitor; empty means all users can edit
items:
type: string
MonitorOptions:
type: object
description: Configuration options for a monitor controlling evaluation, notification, and recovery behavior
properties:
thresholds:
$ref: '#/components/schemas/MonitorThresholds'
notify_no_data:
type: boolean
description: Whether to send a notification when there is no data for the monitored metric
default: false
example: true
no_data_timeframe:
type: integer
description: The number of minutes after which the monitor reports no data (minimum 2x the evaluation timeframe)
example: 42
require_full_window:
type: boolean
description: Whether the monitor requires a full evaluation window of data before alerting
example: true
notify_audit:
type: boolean
description: Whether to send notifications to auditors when the monitor is changed
example: true
renotify_interval:
type: integer
description: The number of minutes between re-notifications while the monitor remains in an alert state (0 to disable)
example: 42
renotify_statuses:
type: array
description: Monitor status types that trigger re-notification messages
items:
type: string
enum:
- alert
- warn
- no data
escalation_message:
type: string
description: The message to include with re-notification alerts instead of the main message
example: CPU usage is high on {{host.name}}
timeout_h:
type: integer
description: The number of hours after which an automatically resolving alert times out
example: 42
evaluation_delay:
type: integer
description: The time in seconds to delay evaluation, used to ensure all data arrives before checking thresholds
example: 42
new_group_delay:
type: integer
description: The number of seconds to delay notification for new monitor groups to allow transient issues to resolve
example: 42
include_tags:
type: boolean
description: Whether to include group scope tags in notification subject and body
default: true
example: true
silenced:
type: object
description: Map of monitor scopes to Unix timestamps indicating when each scope's mute expires (0 for indefinite)
additionalProperties:
type: integer
nullable: true
aggregation:
type: object
description: Aggregation settings used for anomaly and outlier monitors
properties:
type:
type: string
description: The type of aggregation function applied to the metric
metric:
type: string
description: The metric name used in the aggregation
group_by:
type: string
description: The tag key to group the aggregation by
MonitorGroupState:
type: object
description: The state of a single monitor group (a unique combination of tag values)
properties:
status:
type: string
description: The current alert status for this monitor group
enum:
- Alert
- Ignored
- No Data
- OK
- Skipped
- Unknown
- Warn
example: Alert
name:
type: string
description: The name of the monitor group, represented as a comma-separated list of tag:value pairs
example: Example Monitor
last_triggered_ts:
type: integer
format: int64
description: Unix timestamp in seconds of the last time this group triggered an alert
example: 42
last_notified_ts:
type: integer
format: int64
description: Unix timestamp in seconds of the last time a notification was sent for this group
example: 42
last_resolved_ts:
type: integer
format: int64
description: Unix timestamp in seconds of the last time this group resolved from an alert state
example: 42
parameters:
monitorIdParam:
name: monitor_id
in: path
required: true
description: The unique numeric ID of the monitor to operate on
schema:
type: integer
format: int64
securitySchemes:
AuthZ:
description: This API uses OAuth 2 with the implicit grant flow.
flows:
authorizationCode:
authorizationUrl: /oauth2/v1/authorize
scopes:
apm_api_catalog_read: View API catalog and API definitions.
apm_api_catalog_write: Add, modify, and delete API catalog definitions.
apm_read: Read and query APM and Trace Analytics.
apm_service_catalog_read: View service catalog and service definitions.
apm_service_catalog_write: Add, modify, and delete service catalog definitions when those definitions are maintained by Datadog.
appsec_vm_read: View infrastructure, application code, and library vulnerabilities. This does not restrict API or inventory SQL access to the vulnerability data source.
cases_read: View Cases.
cases_write: Create and update cases.
ci_visibility_pipelines_write: Create CI Visibility pipeline spans using the API.
ci_visibility_read: View CI Visibility.
cloud_cost_management_read: View Cloud Cost pages and the cloud cost data source in dashboards and notebooks. For more details, see the Cloud Cost Management docs.
cloud_cost_management_write: Configure cloud cost accounts and global customizations. For more details, see the Cloud Cost Management docs.
code_analysis_read: View Code Analysis.
continuous_profiler_pgo_read: Read and query Continuous Profiler data for Profile-Guided Optimization (PGO).
create_webhooks: Create webhooks integrations.
dashboards_embed_share: Create, modify, and delete shared dashboards with share type 'embed'.
dashboards_invite_share: Create, modify, and delete shared dashboards with share type 'invite'.
dashboards_public_share: Generate public and authenticated links to share dashboards or embeddable graphs externally.
dashboards_read: View dashboards.
dashboards_write: Create and change dashboards.
data_scanner_read: View Data Scanner configurations.
data_scanner_write: Edit Data Scanner configurations.
embeddable_graphs_share: Generate public links to share embeddable graphs externally.
events_read: Read Events data.
hosts_read: List hosts and their attributes.
incident_notification_settings_write: Configure Incidents Notification settings.
incident_read: View incidents in Datadog.
incident_settings_write: Configure Incident Settings.
incident_write: Create, view, and manage incidents in Datadog.
metrics_read: View custom metrics.
monitor_config_policy_write: Edit and delete monitor configuration.
monitors_downtime: Set downtimes to suppress alerts from any monitor in an organization. Mute and unmute monitors. The ability to write monitors is not required to set downtimes.
monitors_read: View monitors.
monitors_write: Edit, delete, and resolve individual monitors.
org_management: Edit org configurations, including authentication and certain security preferences such as configuring SAML, renaming an org, configuring allowed login methods, creating child orgs, subscribing & unsubscribing from apps in the marketplace, and enabling & disabling Remote Configuration for the entire organization.
security_comments_read: Read comments of vulnerabilities.
security_monitoring_filters_read: Read Security Filters.
security_monitoring_filters_write: Create, edit, and delete Security Filters.
security_monitoring_findings_read: View a list of findings that include both misconfigurations and identity risks.
security_monitoring_notification_profiles_read: View Rule Security Notification rules.
security_monitoring_notification_profiles_write: Create, edit, and delete Security Notification rules.
security_monitoring_rules_read: Read Detection Rules.
security_monitoring_rules_write: Create and edit Detection Rules.
security_monitoring_signals_read: View Security Signals.
security_monitoring_suppressions_read: Read Rule Suppressions.
security_monitoring_suppressions_write: Write Rule Suppressions.
security_pipelines_read: View Security Pipelines.
security_pipelines_write: Create, edit, and delete CSM Security Pipelines.
slos_corrections: Apply, edit, and delete SLO status corrections. A user with this permission can make status corrections, even if they do not have permission to edit those SLOs.
slos_read: View SLOs and status corrections.
slos_write: Create, edit, and delete SLOs.
synthetics_global_variable_read: View, search, and use Synthetics global variables.
synthetics_global_variable_write: Create, edit, and delete global variables for Synthetics.
synthetics_private_location_read: View, search, and use Synthetics private locations.
synthetics_private_location_write: Create and delete private locations in addition to having access to the associated installation guidelines.
synthetics_read: List and view configured Synthetic tests and test results.
synthetics_write: Create, edit, and delete Synthetic tests.
teams_manage: Manage Teams. Create, delete, rename, and edit metadata of all Teams. To control Team membership across all Teams, use the User Access Manage permission.
teams_read: Read Teams data. A User with this permission can view Team names, metadata, and which Users are on each Team.
test_optimization_read: View Test Optimization.
timeseries_query: Query Timeseries data.
usage_read: View your organization's usage and usage attribution.
user_access_invite: Invite other users to your organization.
user_access_manage: Disable users, manage user roles, manage SAML-to-role mappings, and configure logs restriction queries.
user_access_read: View users and their roles and settings.
workflows_read: View workflows.
workflows_run: Run workflows.
workflows_write: Create, edit, and delete workflows.
tokenUrl: /oauth2/v1/token
type: oauth2
apiKeyAuth:
description: Your Datadog API Key.
in: header
name: DD-API-KEY
type: apiKey
x-env-name: DD_API_KEY
appKeyAuth:
description: Your Datadog APP Key.
in: header
name: DD-APPLICATION-KEY
type: apiKey
x-env-name: DD_APP_KEY
bearerAuth:
scheme: bearer
type: http
x-env-name: DD_BEARER_TOKEN
x-group-parameters: true
x-merge-override:
paths: false