events
Retrieve, create, and analyze Datadog events with actions for listing, searching, aggregating, and timeseries. Filter monitor alerts by transition type to count real state changes.
Instructions
Track Datadog events. Actions: list, get, create, search, aggregate, top, timeseries, incidents, discover, histogram. For monitor alerts, use tags: ["source:alert"].
IMPORTANT — re-evaluation vs transition:
source:alert events INCLUDE renotifies and re-evaluations (every Datadog re-evaluation of an alerting monitor emits an event). A "how many times did monitor X fire" question answered with source:alert alone over-counts.
To restrict to real state transitions, pass transitionType (e.g. ["alert","alert recovery"]). This appends @monitor.transition.transition_type:(...) to the query and matches the design's live investigation.
For a fires-only numeric count rooted in a single monitor ID, prefer the higher-level primitive monitors action=history — it returns {transitions, count, meta} with the same filter applied for you.
transitionType: Optional array of monitor transition types (alert, alert recovery, warning, warning recovery, no data, no data recovery, renotify). Empty array is treated as undefined. top: Generic event grouping by any fields (groupBy parameter). Returns groups ranked by count with optional context breakdown.
Example: {groupBy: ["service"], message: "...", service: "api", total_count: 50, by_context: [{context: "queue:X", count: 30}]}
Use for deployments, configs, custom events, or monitor alerts
Returns "message" field (event title), NOT monitor name (use monitors tool for real names)
total_count includes renotifies when source:alert is used without transitionType — see monitors action=history for fires-only counts discover: Returns available tag prefixes from events. aggregate: Custom groupBy, returns pipe-delimited keys. search: Full event details. timeseries: Time-bucketed trends with interval. incidents: Deduplicate alerts with dedupeWindow. histogram: Bucket events by local hour_of_day / day_of_week / day_of_month in the requested IANA timezone (DST-safe). Pass bucket_by (required) and optional timezone (default UTC) and cursor (for continuation). Caps at limits.maxEventsForHistogram (default 5000); when reached returns bucketCountIncomplete:true + nextCursor.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| id | No | Event ID (for get action) | |
| query | No | Search query | |
| from | No | Start time (ISO 8601, relative like "1h", or Unix timestamp) | |
| to | No | End time (ISO 8601, relative like "1h", or Unix timestamp) | |
| priority | No | Event priority | |
| sources | No | Filter by sources | |
| tags | No | Filter by tags | |
| limit | No | Maximum number of events to return (default: 50) | |
| title | No | Event title (for create) | |
| text | No | Event text (for create) | |
| alertType | No | Alert type (for create) | |
| groupBy | No | Fields to group by (for aggregate and top actions). Top: custom fields like ["service"], ["user"]. Aggregate: monitor_name, priority, alert_type, source. Default for top: ["monitor_id"] | |
| cursor | No | Pagination cursor from previous response | |
| interval | No | Time bucket interval for timeseries: 1h, 4h, 1d (default: 1h) | |
| dedupeWindow | No | Deduplication window for incidents: 5m, 15m, 1h (default: 5m) | |
| enrich | No | Enrich events with monitor metadata (slower, adds monitor details) | |
| contextTags | No | Tag prefixes for context breakdown in top action (default: queue, service, ingress, pod_name, kube_namespace, kube_container_name) | |
| maxEvents | No | Maximum events to fetch for grouping in top action (default: 5000, max: 5000). Higher = more accurate but slower | |
| transitionType | No | Filter events by monitor state transition type. When set, restricts results to events with @monitor.transition.transition_type matching any value. Use ["alert","alert recovery"] to count real fires/recoveries and skip renotifies. Empty array is treated as undefined (no filter). For a fires-only count by monitor ID, prefer monitors action=history. | |
| bucket_by | No | Bucket dimension for histogram action: hour_of_day (0-23), day_of_week (0=Sun..6=Sat), day_of_month (1-31). | |
| timezone | No | Optional IANA timezone (e.g. "UTC", "Europe/Paris"). DST-safe. For histogram: controls hour/day bucketing (default: UTC). For search/aggregate/top/incidents read actions: adds sibling *Local ISO 8601 strings (e.g. timestampLocal) next to existing timestamps. Omit for byte-identical legacy shape. | |
| fields | No | Search action only: return only these event fields. Allowed values: id, title, message, timestamp, priority, source, tags, alertType, host, monitorId, monitorInfo, monitorMetadata (only populated when enrich=true). Default: full event. |