create_alert
Create a cost alert that monitors one or more queries and notifies when a condition fires. New alerts are creator-only (you get Admin). To share, call set_object_permissions with resourceKind "costAlert". Accepts the same query config as query (prefer datePreset over hand-computed from/to). scopeId is the same id as list_teams. It is stored on the alert and is not merged into the query filters. Omit it for no scope. The firing rule is a single condition boolean expression over the query names, e.g. a > 1000, rollingSum(a, 7, DAY) > 50000, or (a - timeShift(a, 1, DAY)) / timeShift(a, 1, DAY) > 0.2. Window math (rollingSum/weekToDateSum/monthToDateSum/timeShift) is evaluated daily in BigQuery, so you do NOT pick an evaluation period — instead set dedup to control re-notification frequency (CALENDAR once per WEEK/MONTH, or ROLLING once every N days). The period (datePreset or from/to) defines the preview/look-back window for the underlying queries. Use list_available_destinations for SLACK/TEAMS channel IDs. Optional tagIds: existing IDs from list_tags and/or { name, color? } for new tags; color defaults to #6366F1; missing tags are created. Omit and [] both leave the alert untagged. Returns a URL that you MUST include in your response so the user can view/edit the alert.
EXAMPLE: "Alert me on Slack if our production AWS spend exceeds $50k over any 7 days, at most once a week" → { name: "Prod AWS weekly alert", queries: [{ type: "cost", name: "a", metricId: "cost", currency: "USD", filterCel: "cos_provider in ["AWS"] && cos_environment in ["prod"]" }], datePreset: "TRAILING_90_DAYS", condition: "rollingSum(a, 7, DAY) > 50000", dedup: { kind: "CALENDAR", calendarUnit: "WEEK" }, notificationChannel: "SLACK", slackChannelId: "C01ABC" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Explicit window end (inclusive, YYYY-MM-DD). Use with from instead of datePreset. | |
| from | No | Explicit window start (YYYY-MM-DD). Use with to instead of datePreset. | |
| name | Yes | Display name for the alert. | |
| slug | No | Organization slug. Omit to auto-detect from your account (fails if you belong to multiple orgs). | |
| aggBy | No | Time grain for the series: Hour, Day, Week, Month, or Period (default Month). | Month |
| dedup | Yes | Deduplication config controlling how often a still-firing group notifies. The window is per groupBy value; delivery stays one message listing newly eligible groups. Either CALENDAR (kind: CALENDAR, calendarUnit: WEEK | MONTH) = at most once per current ISO week / calendar month, or ROLLING (kind: ROLLING, windowDays: N) = at most once every N days. | |
| limit | No | Max groups/rows per series. Omit to use the default (100). Increase up to 1000 when you need more than 100 breakdown groups. | |
| emails | No | Email addresses (required if EMAIL) | |
| tagIds | No | `list_tags` id or `{ name, color? }` (created if missing, default #6366F1). Omit and [] leave it untagged. | |
| compare | No | Add a comparison period to show cost evolution side-by-side. Omit `from`/`to` to compare against the preceding period automatically; set `chartType` to choose how it renders. | |
| queries | No | Same series objects as the `query` tool `queries` array (cost / metric / usage / externalMetric / formula / budget). Each requires `type` (never omit) and a `name` (prefer short ids like a/b/c); put human labels in `alias`. | |
| scopeId | No | Team scope id (list_teams). Stored on the alert, not merged into query filters. Omit for no scope. | |
| condition | Yes | Alerts v3 firing rule: a single boolean expression over the query names (`name` field of each query). Supports arithmetic (+ - * /), comparisons (> >= < <= == !=), logical and/or/not, parentheses, and these window functions: rollingSum(a, N, UNIT) (trailing sum over the last N units, UNIT ∈ DAY|WEEK|MONTH, inclusive of today), weekToDateSum(a) (Monday-to-date), monthToDateSum(a) (1st-of-month-to-date), and timeShift(a, N, UNIT) (value shifted back N units; may wrap a window function). Examples: `a > 1000`, `rollingSum(a, 7, DAY) > 1000`, `(a - timeShift(a, 1, DAY)) / timeShift(a, 1, DAY) > 0.2`, `a > 10000 or rollingSum(a, 7, DAY) > 50000`. | |
| datePreset | No | Official date preset (same as Explore, e.g. MTD, LAST_MONTH). Forecast: CURRENT_MONTH / CURRENT_QUARTER / CURRENT_YEAR. Mutually exclusive with from/to. | |
| slackChannelId | No | Slack target id (required if SLACK): a channel id (C…) to post to a channel, or a Slack user id (U…) to deliver a direct message to that user. Use list_available_destinations to discover both channels and the signed-in user's DM. | |
| teamsChannelId | No | Teams channel ID (required if TEAMS) | |
| notificationChannel | Yes | Notification channel |