get-alert
dci get-alert id
Returns an alert by the specified Id.
Output
OK - Alert returned.
By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.
| Field | Type | Description |
|---|---|---|
id | string | Alert ID. |
name | string | Alert Name. Default: "". |
createTime | integer (int64) | The time when the alert was created (in UNIX timestamp). |
updateTime | integer (int64) | Last time the alert was modified (in UNIX timestamp). |
lastAlerted | integer (int64) | Last time the alert was triggered (in UNIX timestamp). |
recipients | array of string | List of emails that will be notified when the alert is triggered. |
config | object | Parameters that define when and how an alert is evaluated. |
config.dataSource | string | Data source used to query data for the alert. Affects which dimensions and metrics are available. One of: "billing", "billing-datahub". Default: "billing". |
config.scopes | array of object | 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. |
config.scopes[].id | string | 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. |
config.scopes[].type | string | 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. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "attribution", "attribution_group", "allocation", "allocation_rule", "gke", …. |
config.scopes[].values | array of string | 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. |
config.scopes[].mode | string | Controls how the dimension’s values are matched when the alert query runs. If mode is omitted, behavior defaults to is. One of: "is", "starts_with", "ends_with", "contains", "regexp". |
config.scopes[].inverse | boolean | Set to true to exclude the set values. If inverse is omitted, behavior defaults to false. |
config.scopes[].caseInsensitive | boolean | If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise. Default: false. |
config.scopes[].includeNull | boolean | Include rows where the dimension is null. If includeNull is omitted, behavior defaults to false. Default: false. |
config.metric | object | Define how metrics are selected and filtered in reports. |
config.metric.type | string | Identifier for metric type (e.g., basic, custom, extended). |
config.metric.value | string | |
config.currency | string | Currency code for monetary values. One of: "USD", "ILS", "EUR", "AUD", "CAD", "GBP", "DKK", "NOK", "SEK", "BRL", "SGD", "MXN", …. |
config.timeInterval | string | The period each evaluation looks at. One of: "day", "week", "month", "quarter", "year". Default: "year". |
config.condition | string | Type of comparison for the alert threshold (used with operator and value). If omitted on create, defaults to percentage-change. One of: "value", "percentage-change", "forecast". Default: "percentage-change". |
config.operator | string | Text/operator used to filter metric values in metric filters (gt = greater than, lt = less than). One of: "gt", "lt". |
config.value | number (double) | The condition threshold value. For example, actual metric threshold value for the value condition, or percentage change threshold value for the percentage-change condition. |
config.evaluateForEach | string | 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. |
config.attributions | array of string | Use 'scopes' instead. The attributions selected define the scope to monitor. |
Example response (--output json)
{
"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
}
}
Raw JSON schema
{
"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
}
}
}
Errors
On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.
| HTTP status | Exit code | Error code | Meaning |
|---|---|---|---|
| 400 | 30 | VALIDATION_ERROR | The arguments or request body were rejected. Review the command's flags and payload. |
| 401 | 10 | AUTHENTICATION_FAILED | Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY. |
| 403 | 11 | PERMISSION_DENIED | The DoiT user or the active customer context does not have access. |
| 404 | 20 | RESOURCE_NOT_FOUND | The requested resource does not exist. Check the identifier argument. |
Aliases: getalert