list-budgets
dci list-budgets [flags]
Returns a list of budgets that your account has access to. Budgets are listed in reverse chronological order by default.
Each budget includes a server-computed riskStatus (atRisk, onTrack, or unknown), and the response includes a riskAggregations summary of risk counts across the full filtered result set (all pages, not just the current page).
Flags
--max-results: (integer format:int64 default:50)
--page-token: (string)
--filter: (string)
--name-contains: (string)
--min-creation-time: (string)
--max-creation-time: (string)
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 |
|---|---|---|
budgets | array of object | Array of Budgets |
budgets[].alertThresholds | array of object | |
budgets[].alertThresholds[].amount | number (double) | |
budgets[].alertThresholds[].percentage | number (double) | |
budgets[].amount | number (double) | |
budgets[].budgetName | string | |
budgets[].createTime | integer (int64) | |
budgets[].currency | string | |
budgets[].currentUtilization | number (double) | |
budgets[].endPeriod | integer (int64) | |
budgets[].forecastedUtilizationDate | integer (int64) | |
budgets[].id | string | |
budgets[].owner | string | |
budgets[].riskStatus | string | Server-computed risk classification, based on current utilization and forecasted breach date relative to the configured amount and current period end. "atRisk" - the budget has already exceeded its configured amount, or its forecast projects it will before the current period ends. "onTrack" - the budget has forecast data and is neither over budget nor projected to breach. "unknown" - no forecast data is available yet, the budget is a fixed budget whose period has already expired, or the budget is invalid/draft. One of: "atRisk", "onTrack", "unknown". |
budgets[].scope | array of string | List of allocations that define the budget scope. |
budgets[].scopes | array of object | The filters selected define the scope of the budget. |
budgets[].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. |
budgets[].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", …. |
budgets[].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. |
budgets[].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". |
budgets[].scopes[].inverse | boolean | Set to true to exclude the set values. If inverse is omitted, behavior defaults to false. |
budgets[].scopes[].caseInsensitive | boolean | If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise. Default: false. |
budgets[].scopes[].includeNull | boolean | Include rows where the dimension is null. If includeNull is omitted, behavior defaults to false. Default: false. |
budgets[].startPeriod | integer (int64) | |
budgets[].timeInterval | string | |
budgets[].updateTime | integer (int64) | |
budgets[].url | string | |
pageToken | string | Page token, returned by a previous call, to request the next page of results |
rowCount | integer (int64) | Budgets rows count |
riskAggregations | object | Aggregate counts of risk statuses across the full filtered result set (all pages), not just the current page. |
riskAggregations.total | integer (int64) | |
riskAggregations.atRisk | integer (int64) | |
riskAggregations.onTrack | integer (int64) | |
riskAggregations.unknown | integer (int64) |
Raw JSON schema
{
"type": "object",
"properties": {
"budgets": {
"type": "array",
"description": "Array of Budgets",
"items": {
"type": "object",
"description": "Summary information for a budget.",
"properties": {
"alertThresholds": {
"type": "array",
"items": {
"type": "object",
"description": "A numeric or percentage threshold.",
"properties": {
"amount": {
"type": "number",
"format": "double"
},
"percentage": {
"type": "number",
"format": "double"
}
}
}
},
"amount": {
"type": "number",
"format": "double"
},
"budgetName": {
"type": "string"
},
"createTime": {
"type": "integer",
"format": "int64"
},
"currency": {
"type": "string"
},
"currentUtilization": {
"type": "number",
"format": "double"
},
"endPeriod": {
"type": "integer",
"format": "int64"
},
"forecastedUtilizationDate": {
"type": "integer",
"format": "int64"
},
"id": {
"type": "string"
},
"owner": {
"type": "string"
},
"riskStatus": {
"type": "string",
"description": "Server-computed risk classification, based on current utilization and forecasted breach date relative to the configured amount and current period end.\n\"atRisk\" - the budget has already exceeded its configured amount, or its forecast projects it will before the current period ends.\n\"onTrack\" - the budget has forecast data and is neither over budget nor projected to breach.\n\"unknown\" - no forecast data is available yet, the budget is a fixed budget whose period has already expired, or the budget is invalid/draft.",
"enum": [
"atRisk",
"onTrack",
"unknown"
]
},
"scope": {
"type": "array",
"description": "List of allocations that define the budget scope.",
"items": {
"type": "string"
},
"deprecated": true
},
"scopes": {
"type": "array",
"description": "The filters selected define the scope of the budget.",
"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"
]
}
}
},
"startPeriod": {
"type": "integer",
"format": "int64"
},
"timeInterval": {
"type": "string"
},
"updateTime": {
"type": "integer",
"format": "int64"
},
"url": {
"type": "string"
}
}
}
},
"pageToken": {
"type": "string",
"description": "Page token, returned by a previous call, to request the next page of results"
},
"rowCount": {
"type": "integer",
"description": "Budgets rows count",
"format": "int64"
},
"riskAggregations": {
"type": "object",
"description": "Aggregate counts of risk statuses across the full filtered result set (all pages), not just the current page.",
"required": [
"total",
"atRisk",
"onTrack",
"unknown"
],
"properties": {
"total": {
"type": "integer",
"format": "int64"
},
"atRisk": {
"type": "integer",
"format": "int64"
},
"onTrack": {
"type": "integer",
"format": "int64"
},
"unknown": {
"type": "integer",
"format": "int64"
}
}
}
}
}
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: listbudgets