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).

CLI default view

dci list-budgets presents a curated table by default:

Columns: budget name (a clickable link to the budget in the DoiT console in interactive terminals), owner, amount and spend to date (from currentUtilization; both carry the budget's currency symbol), risk (from riskStatus), and updated (UTC).
In interactive tables, updated (UTC) renders in your local timezone and is titled updated (local); machine formats, agent mode, and --utc keep UTC — see Timestamps and timezones.
The API's row order is kept — notably the projected-breach-date order under --filter riskStatus:atRisk.
--output json and explicit -C/--fields selections return the raw fields documented below.

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

Flags​

Output​

Errors​

Flags

Output

Errors