create-alert
dci create-alert
Creates a new alert.
Request
Content-Type: application/json
Example
{
"config": {
"metric": {
"type": "basic",
"value": "cost"
},
"timeInterval": "year",
"operator": "gt",
"scopes": [
{
"key": "service_description",
"type": "fixed",
"values": [
"Amazon Simple Storage Service"
]
}
],
"condition": "value",
"currency": "USD",
"value": 1000
},
"name": "test08"
}
Schema
{
"required": [
"config",
"name"
],
"type": "object",
"description": "Request body for creating a new alert.",
"properties": {
"name": {
"type": "string",
"description": "Name of the alert (max 64 characters)."
},
"config": {
"type": "object",
"description": "Parameters that define when and how an alert is evaluated.",
"required": [
"metric",
"timeInterval",
"value"
],
"properties": {
"dataSource": {
"type": "string",
"description": "Data source used to query data for the alert. Affects which dimensions and metrics are available.",
"default": "billing",
"enum": [
"billing",
"billing-datahub"
],
"x-enumDescriptions": {
"billing": "Standard Cloud Analytics billing data only.",
"billing-datahub": "Billing data plus DataHub custom dimensions and metrics (requires a DataHub subscription)."
}
},
"scopes": {
"type": "array",
"description": "The filters that define the scope of the alert. Each item is a Cloud Analytics filter (same idea as report filters). Note: Only the first scope in the array is currently applied; any additional scopes are validated but ignored. If additional scopes are malformed the call will fail silently. Use a single, well-chosen filter, or dataSource plus evaluateForEach to slice spend instead.",
"items": {
"description": "To include or exclude certain values.\nWhen using allocation rules as a filter, both the type and the ID must be \"allocation_rule\", and the values array contains the allocation rule IDs.\nWhen using allocations as a filter, the type must be \"allocation\" and the ID is the actual allocation group ID.",
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Dimension key to filter on. Must pair with `type` and match a dimension returned by `GET /analytics/v1/dimensions` (for example, `service_description` with `type: fixed`). For `allocation_rule`, use `allocation_rule`. For `allocation`, use the allocation group ID. See `DimensionsTypes` for how each `type` uses `id`."
},
"type": {
"description": "Dimension filter type. Always pair `type` with `id` on scope filters. Discover valid `id` + `type` pairs for your account with `GET /analytics/v1/dimensions`. `allocation_rule` replaces `attribution`; `allocation` replaces `attribution_group`.",
"type": "string",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"allocation",
"allocation_rule",
"gke",
"gke_label"
],
"x-enumDescriptions": {
"fixed": "Standard built-in billing dimensions (Service, Provider, Project/Account ID, SKU, Region, etc.).",
"label": "Customer-defined resource labels; id is the label key, values are label values.",
"tag": "AWS cost allocation tags; id is the tag key.",
"project_label": "Google Cloud project-level labels; id is the label key.",
"system_label": "DoiT- or provider-generated system labels; id is the system label key.",
"optional": "Console grouping for label/tag keys; use label, tag, project_label, or system_label in API scopes.",
"datetime": "Time dimensions (Year, Month, Day) for date-based filtering or grouping.",
"allocation_rule": "Allocation rule filter; id must be allocation_rule, values are rule IDs.",
"allocation": "Allocation group filter; id is the allocation group ID.",
"gke": "Google Kubernetes Engine cost-allocation dimensions.",
"gke_label": "GKE workload labels; id is the label key.",
"attribution": "Deprecated. Use allocation_rule.",
"attribution_group": "Deprecated. Use allocation."
}
},
"values": {
"type": "array",
"description": "List of values to include or exclude. Must match exact strings from your billing or DataHub data for the dimension (for example, `Amazon Simple Storage Service` for AWS S3 on `service_description`). For `allocation_rule`, use allocation rule IDs.",
"items": {
"type": "string"
}
},
"mode": {
"type": "string",
"description": "Controls how the dimension’s `values` are matched when the alert query runs. If mode is omitted, behavior defaults to is.",
"enum": [
"is",
"starts_with",
"ends_with",
"contains",
"regexp"
],
"x-enumDescriptions": {
"is": "Exact match on one or more values.",
"starts_with": "Value starts with the given string(s).",
"ends_with": "Value ends with the given string(s).",
"contains": "Value contains the given string(s).",
"regexp": "Value matches the regular expression in `values` (exactly one pattern)."
}
},
"inverse": {
"type": "boolean",
"description": "Set to `true` to exclude the set values. If inverse is omitted, behavior defaults to `false`."
},
"caseInsensitive": {
"type": "boolean",
"description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise.",
"default": false
},
"includeNull": {
"type": "boolean",
"description": "Include rows where the dimension is null. If includeNull is omitted, behavior defaults to `false`.",
"default": false
}
},
"example": {
"id": "cloud_provider",
"type": "fixed",
"inverse": false,
"values": [
"google-cloud"
]
}
}
},
"metric": {
"type": "object",
"description": "Define how metrics are selected and filtered in reports.",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"description": "Identifier for metric type (e.g., basic, custom, extended)."
},
"value": {
"type": "string"
}
}
},
"currency": {
"description": "Currency code for monetary values.",
"type": "string",
"enum": [
"USD",
"ILS",
"EUR",
"AUD",
"CAD",
"GBP",
"DKK",
"NOK",
"SEK",
"BRL",
"SGD",
"MXN",
"CHF",
"MYR",
"TWD",
"EGP",
"ZAR",
"JPY",
"IDR",
"AED",
"THB",
"COP"
]
},
"timeInterval": {
"type": "string",
"description": "The period each evaluation looks at.",
"default": "year",
"enum": [
"day",
"week",
"month",
"quarter",
"year"
]
},
"condition": {
"type": "string",
"description": "Type of comparison for the alert threshold (used with `operator` and `value`). If omitted on create, defaults to `percentage-change`.",
"default": "percentage-change",
"enum": [
"value",
"percentage-change",
"forecast"
],
"x-enumDescriptions": {
"value": "Actual metric in the selected period (console condition \"is\"). Example — monthly cost is greater than $100.",
"percentage-change": "Percent change versus the previous period (console condition \"percentage change is\"). Example — daily cost increased by more than 20%.",
"forecast": "Forecasted metric for the period (console condition \"is forecasted to be\"). Cannot be combined with `evaluateForEach`."
}
},
"operator": {
"type": "string",
"description": "Text/operator used to filter metric values in metric filters (gt = greater than, lt = less than).",
"enum": [
"gt",
"lt"
]
},
"value": {
"type": "number",
"format": "double",
"description": "The `condition` threshold value. For example, actual metric threshold value for the `value` condition, or percentage change threshold value for the `percentage-change` condition."
},
"evaluateForEach": {
"type": "string",
"description": "Add a dimension to break down the evaluation of the condition. For example, evaluate a condition over an attribution for each \"Service\". Must be a dimension key returned by GET /analytics/v1/dimensions. Not allowed with condition: `forecast`. Used when you Investigate an alert, the dimension becomes the report grouping."
},
"attributions": {
"type": "array",
"deprecated": true,
"description": "Use 'scopes' instead. The attributions selected define the scope to monitor.",
"items": {
"type": "string"
}
}
}
},
"recipients": {
"type": "array",
"description": "List of emails to notify when the alert is triggered. If omitted on create, defaults to the API user’s email. Must match allowed customer domains.",
"items": {
"type": "string"
}
}
},
"example": {
"config": {
"metric": {
"type": "basic",
"value": "cost"
},
"timeInterval": "year",
"operator": "gt",
"scopes": [
{
"key": "service_description",
"type": "fixed",
"values": [
"Amazon Simple Storage Service"
]
}
],
"condition": "value",
"currency": "USD",
"value": 1000
},
"name": "test08"
}
}
Responses
201 (application/json)
Created - The request succeeded.
{
"required": [
"name"
],
"type": "object",
"description": "Configuration and runtime metadata of an alert.",
"properties": {
"id": {
"type": "string",
"description": "Alert ID."
},
"name": {
"type": "string",
"description": "Alert Name.",
"default": ""
},
"createTime": {
"type": "integer",
"description": "The time when the alert was created (in UNIX timestamp).",
"format": "int64"
},
"updateTime": {
"type": "integer",
"description": "Last time the alert was modified (in UNIX timestamp).",
"format": "int64"
},
"lastAlerted": {
"type": "integer",
"description": "Last time the alert was triggered (in UNIX timestamp).",
"format": "int64"
},
"recipients": {
"type": "array",
"description": "List of emails that will be notified when the alert is triggered.",
"items": {
"type": "string"
}
},
"config": {
"type": "object",
"description": "Parameters that define when and how an alert is evaluated.",
"required": [
"metric",
"timeInterval",
"value"
],
"properties": {
"dataSource": {
"type": "string",
"description": "Data source used to query data for the alert. Affects which dimensions and metrics are available.",
"default": "billing",
"enum": [
"billing",
"billing-datahub"
],
"x-enumDescriptions": {
"billing": "Standard Cloud Analytics billing data only.",
"billing-datahub": "Billing data plus DataHub custom dimensions and metrics (requires a DataHub subscription)."
}
},
"scopes": {
"type": "array",
"description": "The filters that define the scope of the alert. Each item is a Cloud Analytics filter (same idea as report filters). Note: Only the first scope in the array is currently applied; any additional scopes are validated but ignored. If additional scopes are malformed the call will fail silently. Use a single, well-chosen filter, or dataSource plus evaluateForEach to slice spend instead.",
"items": {
"description": "To include or exclude certain values.\nWhen using allocation rules as a filter, both the type and the ID must be \"allocation_rule\", and the values array contains the allocation rule IDs.\nWhen using allocations as a filter, the type must be \"allocation\" and the ID is the actual allocation group ID.",
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Dimension key to filter on. Must pair with `type` and match a dimension returned by `GET /analytics/v1/dimensions` (for example, `service_description` with `type: fixed`). For `allocation_rule`, use `allocation_rule`. For `allocation`, use the allocation group ID. See `DimensionsTypes` for how each `type` uses `id`."
},
"type": {
"description": "Dimension filter type. Always pair `type` with `id` on scope filters. Discover valid `id` + `type` pairs for your account with `GET /analytics/v1/dimensions`. `allocation_rule` replaces `attribution`; `allocation` replaces `attribution_group`.",
"type": "string",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"allocation",
"allocation_rule",
"gke",
"gke_label"
],
"x-enumDescriptions": {
"fixed": "Standard built-in billing dimensions (Service, Provider, Project/Account ID, SKU, Region, etc.).",
"label": "Customer-defined resource labels; id is the label key, values are label values.",
"tag": "AWS cost allocation tags; id is the tag key.",
"project_label": "Google Cloud project-level labels; id is the label key.",
"system_label": "DoiT- or provider-generated system labels; id is the system label key.",
"optional": "Console grouping for label/tag keys; use label, tag, project_label, or system_label in API scopes.",
"datetime": "Time dimensions (Year, Month, Day) for date-based filtering or grouping.",
"allocation_rule": "Allocation rule filter; id must be allocation_rule, values are rule IDs.",
"allocation": "Allocation group filter; id is the allocation group ID.",
"gke": "Google Kubernetes Engine cost-allocation dimensions.",
"gke_label": "GKE workload labels; id is the label key.",
"attribution": "Deprecated. Use allocation_rule.",
"attribution_group": "Deprecated. Use allocation."
}
},
"values": {
"type": "array",
"description": "List of values to include or exclude. Must match exact strings from your billing or DataHub data for the dimension (for example, `Amazon Simple Storage Service` for AWS S3 on `service_description`). For `allocation_rule`, use allocation rule IDs.",
"items": {
"type": "string"
}
},
"mode": {
"type": "string",
"description": "Controls how the dimension’s `values` are matched when the alert query runs. If mode is omitted, behavior defaults to is.",
"enum": [
"is",
"starts_with",
"ends_with",
"contains",
"regexp"
],
"x-enumDescriptions": {
"is": "Exact match on one or more values.",
"starts_with": "Value starts with the given string(s).",
"ends_with": "Value ends with the given string(s).",
"contains": "Value contains the given string(s).",
"regexp": "Value matches the regular expression in `values` (exactly one pattern)."
}
},
"inverse": {
"type": "boolean",
"description": "Set to `true` to exclude the set values. If inverse is omitted, behavior defaults to `false`."
},
"caseInsensitive": {
"type": "boolean",
"description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise.",
"default": false
},
"includeNull": {
"type": "boolean",
"description": "Include rows where the dimension is null. If includeNull is omitted, behavior defaults to `false`.",
"default": false
}
},
"example": {
"id": "cloud_provider",
"type": "fixed",
"inverse": false,
"values": [
"google-cloud"
]
}
}
},
"metric": {
"type": "object",
"description": "Define how metrics are selected and filtered in reports.",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"description": "Identifier for metric type (e.g., basic, custom, extended)."
},
"value": {
"type": "string"
}
}
},
"currency": {
"description": "Currency code for monetary values.",
"type": "string",
"enum": [
"USD",
"ILS",
"EUR",
"AUD",
"CAD",
"GBP",
"DKK",
"NOK",
"SEK",
"BRL",
"SGD",
"MXN",
"CHF",
"MYR",
"TWD",
"EGP",
"ZAR",
"JPY",
"IDR",
"AED",
"THB",
"COP"
]
},
"timeInterval": {
"type": "string",
"description": "The period each evaluation looks at.",
"default": "year",
"enum": [
"day",
"week",
"month",
"quarter",
"year"
]
},
"condition": {
"type": "string",
"description": "Type of comparison for the alert threshold (used with `operator` and `value`). If omitted on create, defaults to `percentage-change`.",
"default": "percentage-change",
"enum": [
"value",
"percentage-change",
"forecast"
],
"x-enumDescriptions": {
"value": "Actual metric in the selected period (console condition \"is\"). Example — monthly cost is greater than $100.",
"percentage-change": "Percent change versus the previous period (console condition \"percentage change is\"). Example — daily cost increased by more than 20%.",
"forecast": "Forecasted metric for the period (console condition \"is forecasted to be\"). Cannot be combined with `evaluateForEach`."
}
},
"operator": {
"type": "string",
"description": "Text/operator used to filter metric values in metric filters (gt = greater than, lt = less than).",
"enum": [
"gt",
"lt"
]
},
"value": {
"type": "number",
"format": "double",
"description": "The `condition` threshold value. For example, actual metric threshold value for the `value` condition, or percentage change threshold value for the `percentage-change` condition."
},
"evaluateForEach": {
"type": "string",
"description": "Add a dimension to break down the evaluation of the condition. For example, evaluate a condition over an attribution for each \"Service\". Must be a dimension key returned by GET /analytics/v1/dimensions. Not allowed with condition: `forecast`. Used when you Investigate an alert, the dimension becomes the report grouping."
},
"attributions": {
"type": "array",
"deprecated": true,
"description": "Use 'scopes' instead. The attributions selected define the scope to monitor.",
"items": {
"type": "string"
}
}
}
}
},
"example": {
"id": "7jyrczd6CSh3M8TuQ6Qq",
"name": "fgfgh",
"createTime": 1678628817062,
"updateTime": 1678628938891,
"lastAlerted": null,
"recipients": [
],
"config": {
"condition": "value",
"currency": "USD",
"metric": {
"type": "basic",
"value": "cost"
},
"operator": "gt",
"evaluateForEach": "",
"attributions": [
"PvqyGcdFcTHh7aLUdGdf"
],
"scopes": [],
"timeInterval": "month",
"dataSource": "billing",
"value": 500
}
}
}
400 (application/json)
Bad Request - The server cannot process the request, often due to a malformed request.
{
"type": "object",
"description": "Standard error response structure.",
"properties": {
"error": {
"type": "string",
"description": "Detailed error message."
}
}
}
401 (application/json)
Unauthorized - Invalid API key.
{
"type": "object",
"description": "Standard error response structure.",
"properties": {
"error": {
"type": "string",
"description": "Detailed error message."
}
}
}
403 (application/json)
Forbidden - The client is not authorized to perform the request.
{
"type": "object",
"description": "Standard error response structure.",
"properties": {
"error": {
"type": "string",
"description": "Detailed error message."
}
}
}
404 (application/json)
Not Found - The requested resource does not exist.
{
"type": "object",
"description": "Standard error response structure.",
"properties": {
"error": {
"type": "string",
"description": "Detailed error message."
}
}
}
Aliases: create-alert, createalert