list-alerts
dci list-alerts [flags]
Returns a list of alerts that your account has access to. Alerts are listed in reverse chronological order by default.
CLI default view
dci list-alerts presents a curated table by default:
- Columns:
name,owner,last alerted (UTC)(fromlastAlerted; blank when the alert never fired), andupdated (UTC). - In interactive tables,
last alerted (UTC)andupdated (UTC)render in your local timezone (titled(local)); machine formats, agent mode, and--utckeep UTC — see Timestamps and timezones. - Rows are sorted by last update, newest first.
--output jsonand explicit-C/--fieldsselections return the raw fields documented below.
Examples
# Your alerts, newest update first.
dci list-alerts
# Alerts owned by one person, most recently fired first.
# Alerts whose name contains a word (ANDs with --filter).
dci list-alerts --name-contains "S3"
# Every page as JSON, for scripts.
dci list-alerts --all --output json
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--sort-by | string | A field by which the results will be sorted. One of: "name", "createTime", "updateTime", "lastAlerted". | ||
--sort-order | string | Specifies the sort direction; accepts asc for ascending (lowest to highest) or desc for descending (highest to lowest). One of: "asc", "desc". | ||
--max-results | integer (int64) | 50 | The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection. | |
--page-token | string | Page token, returned by a previous call, to request the next page of results | ||
--filter | string | name:test | An expression for filtering the results. The syntax is key:[<value>]. Multiple filters can be connected using a pipe |. See Filters. Available filter keys: owner, name | |
--name-contains | string | monthly spend | Case-insensitive substring match against the resource name. Combined with the "filter" parameter using AND semantics. |
Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.
Output
OK - The request succeeded.
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 |
|---|---|---|
pageToken | string | Page token. It is used to request a specific page of the list results. |
rowCount | integer (int64) | The number of returned records. |
alerts | array of object | Array of alerts. |
alerts[].owner | string | Email of the alert owner (the collaborator with the owner role). |
alerts[].id | string | Alert ID. |
alerts[].name | string | Alert Name. Default: "". |
alerts[].createTime | integer (int64) | The time when the alert was created (in Unix milliseconds). |
alerts[].updateTime | integer (int64) | Last time the alert was modified (in Unix milliseconds). |
alerts[].lastAlerted | integer (int64) | Last notification activity in Unix milliseconds. Slack advances this on the first provider acceptance for a detection, which does not confirm final delivery. |
alerts[].recipientsSlackChannels | array of object | Slack destinations. Omitted on create means none; omitted on PATCH preserves saved channels; an array replaces them and [] clears them. Null is rejected. Order is preserved as submitted and repeated destinations are collapsed. At least one email or Slack destination must remain. Discover eligible destinations with listAlertSlackChannels. |
alerts[].recipientsSlackChannels[].id | string | |
alerts[].recipientsSlackChannels[].workspace | string | Connected workspace name returned by discovery. Required for a non-shared channel. |
alerts[].recipientsSlackChannels[].shared | boolean | Default: false. |
alerts[].recipientsSlackChannels[].customerId | string | |
alerts[].recipientsSlackChannels[].name | string | Display name, resolved server-side. |
alerts[].recipientsSlackChannels[].type | string | Channel visibility, resolved server-side. One of: "public", "private". |
alerts[].recipients | array of string | List of emails that will be notified when the alert is triggered. |
alerts[].config | object | Parameters that define when and how an alert is evaluated. |
alerts[].config.ignoreValuesRange | object | Ignore metric values within these inclusive bounds for percentage-change alerts. Bounds use the metric units, not percentage-change units, and must satisfy lowerBound <= upperBound. Omission on PATCH preserves the range; null clears it. Changing condition away from percentage-change clears the range; supplying a non-null range with another condition is rejected. |
alerts[].config.ignoreValuesRange.lowerBound | number (double) | |
alerts[].config.ignoreValuesRange.upperBound | number (double) | |
alerts[].config.dataSource | string | Data source used to query data for the alert. Affects which dimensions and metrics are available. One of: "billing", "billing-datahub", "kubernetes-utilization", "tokenomics". Default: "billing". |
alerts[].config.scopes | array of object | All supplied filters are applied together (AND across filters). Values within each filter follow its matching mode. Nonempty scopes replace legacy attributions. On PATCH, omission preserves scopes and [] clears them. With neither scopes nor attributions, evaluation covers all available billing data for the customer. |
alerts[].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. |
alerts[].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", …. |
alerts[].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. |
alerts[].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". |
alerts[].config.scopes[].inverse | boolean | Set to true to exclude the set values. If inverse is omitted, behavior defaults to false. |
alerts[].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. |
alerts[].config.scopes[].includeNull | boolean | Include rows where the dimension is null. If includeNull is omitted, behavior defaults to false. Default: false. |
alerts[].config.metric | object | Define how metrics are selected and filtered in reports. |
alerts[].config.metric.type | string | Identifier for metric type (e.g., basic, custom, extended). |
alerts[].config.metric.value | string | |
alerts[].config.currency | string | Currency code for monetary values. One of: "USD", "ILS", "EUR", "AUD", "CAD", "GBP", "DKK", "NOK", "SEK", "BRL", "SGD", "MXN", …. |
alerts[].config.timeInterval | string | The period each evaluation looks at. One of: "day", "week", "month", "quarter", "year". |
alerts[].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". |
alerts[].config.operator | string | Text/operator used to filter metric values in metric filters (gt = greater than, lt = less than). One of: "gt", "lt". |
alerts[].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. |
alerts[].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". Use type:id from GET /analytics/v1/dimensions, for example fixed:service_description. An empty string on PATCH clears the breakdown. Not allowed with condition: forecast. Used when you Investigate an alert, the dimension becomes the report grouping. |
Raw JSON schema
{
"type": "object",
"description": "List of alerts.",
"properties": {
"pageToken": {
"type": "string",
"description": "Page token. It is used to request a specific page of the list results.",
"example": "bDl0QkEwVFZxUEwxaUJRaHhTcXM"
},
"rowCount": {
"type": "integer",
"description": "The number of returned records.",
"format": "int64",
"example": 1
},
"alerts": {
"type": "array",
"description": "Array of alerts.",
"items": {
"description": "Alert as returned by the list endpoint. Identical to `Alert` but also includes `owner`. The `owner` field is only populated in list results; it is not returned by the get, create, or update endpoints.",
"allOf": [
{
"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 milliseconds).",
"format": "int64"
},
"updateTime": {
"type": "integer",
"description": "Last time the alert was modified (in Unix milliseconds).",
"format": "int64"
},
"lastAlerted": {
"type": "integer",
"description": "Last notification activity in Unix milliseconds. Slack advances this on the first provider acceptance for a detection, which does not confirm final delivery.",
"nullable": true,
"format": "int64"
},
"recipientsSlackChannels": {
"type": "array",
"maxItems": 50,
"description": "Slack destinations. Omitted on create means none; omitted on PATCH preserves saved channels; an array replaces them and [] clears them. Null is rejected. Order is preserved as submitted and repeated destinations are collapsed. At least one email or Slack destination must remain. Discover eligible destinations with listAlertSlackChannels.",
"items": {
"type": "object",
"required": [
"id"
],
"description": "Eligible Slack destination returned by listAlertSlackChannels. Exactly one of the two shapes is valid: a shared channel (`shared: true`, `workspace` omitted), or a workspace channel (`shared: false` or omitted, `workspace` required). Any other combination is rejected with `validation_failed`. Identity is id plus workspace/shared context. customerId defaults to the authenticated customer; an explicit mismatch is rejected. Name and type are canonical display metadata. Existing unavailable destinations may be retained or removed. Service accounts can add public/shared destinations; new private destinations require a user credential with channel visibility.",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"workspace": {
"type": "string",
"description": "Connected workspace name returned by discovery. Required for a non-shared channel."
},
"shared": {
"type": "boolean",
"default": false
},
"customerId": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"description": "Display name, resolved server-side."
},
"type": {
"type": "string",
"description": "Channel visibility, resolved server-side.",
"enum": [
"public",
"private"
]
}
}
}
},
"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",
"operator"
],
"properties": {
"ignoreValuesRange": {
"type": "object",
"nullable": true,
"required": [
"lowerBound",
"upperBound"
],
"description": "Ignore metric values within these inclusive bounds for percentage-change alerts. Bounds use the metric units, not percentage-change units, and must satisfy lowerBound <= upperBound. Omission on PATCH preserves the range; null clears it. Changing condition away from percentage-change clears the range; supplying a non-null range with another condition is rejected.",
"properties": {
"lowerBound": {
"type": "number",
"format": "double"
},
"upperBound": {
"type": "number",
"format": "double"
}
}
},
"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",
"kubernetes-utilization",
"tokenomics"
],
"x-enumDescriptions": {
"billing": "Standard Cloud Analytics billing data only.",
"billing-datahub": "Billing data plus DataHub custom dimensions and metrics (requires a DataHub subscription).",
"kubernetes-utilization": "Kubernetes utilization data.",
"tokenomics": "Tokenomics data; requires the customer to have Tokenomics enabled."
}
},
"scopes": {
"type": "array",
"description": "All supplied filters are applied together (AND across filters). Values within each filter follow its matching mode. Nonempty scopes replace legacy attributions. On PATCH, omission preserves scopes and [] clears them. With neither scopes nor attributions, evaluation covers all available billing data for the customer.",
"maxItems": 26,
"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.",
"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\". Use type:id from GET /analytics/v1/dimensions, for example fixed:service_description. An empty string on PATCH clears the breakdown. Not allowed with condition: `forecast`. Used when you Investigate an alert, the dimension becomes the report grouping."
}
}
}
},
"example": {
"id": "7jyrczd6CSh3M8TuQ6Qq",
"name": "fgfgh",
"createTime": 1678628817062,
"updateTime": 1678628938891,
"lastAlerted": null,
"recipientsSlackChannels": [],
"recipients": [
],
"config": {
"condition": "value",
"currency": "USD",
"metric": {
"type": "basic",
"value": "cost"
},
"operator": "gt",
"evaluateForEach": "",
"scopes": [
{
"id": "attribution",
"type": "attribution",
"values": [
"PvqyGcdFcTHh7aLUdGdf"
]
}
],
"timeInterval": "month",
"dataSource": "billing",
"value": 500
}
}
},
{
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Email of the alert owner (the collaborator with the owner role)."
}
}
}
]
}
}
}
}
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 to exit code mapping
| 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. |
Related
- get-alert — Retrieve an alert
- create-alert — Create an alert
- update-alert — Update an alert
- delete-alert — Delete an alert
- API reference: GET /analytics/v1/alerts
Aliases: listalerts