update-budget

dci update-budget <id> [body]

Updates the specified budget.

• id — Budget ID or name as shown by dci list-budgets. Names resolve (exact, unique substring, or close typo); pass --id to force a literal ID.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Examples

# Raise the period amount.
dci update-budget "Team Backyard" amount: 12000

# Set alert thresholds and who is notified.
dci update-budget <budget-id> alerts: [{percentage: 50}, {percentage: 75}, {percentage: 90}], recipients: [[email protected], [email protected]]

# Pull the current budget, edit it, and push it back as code.
dci update-budget <budget-id> < budget.json

Start from `dci get-budget <budget-id> --output json > budget.json`, edit, then push; the response is the updated budget with its utilization.

# Replace the scope with the body read from a file.
dci update-budget <budget-id> < budget.json

# budget.json
{"scopes": [{"id": "cloud_provider", "type": "fixed", "mode": "is",
             "values": ["amazon-web-services", "google-cloud"]}]}

Request

Content-Type: application/json

Field	Type	Required	Description
alerts	array of object		List of up to three thresholds defined as a percentage of the amount.
alerts[].percentage	number (double)
amount	number (double)		Budget period amount required: true(if usePrevSpend is false)
seasonalAmounts	array of number (double)		List of seasonal amounts for recurring budgets with different amounts per period.
collaborators	array of object		List of permitted users to view/edit the report.
collaborators[].email	string
collaborators[].role	string		One of: "owner", "editor", "viewer".
currency	string		Currency code for monetary values. One of: "USD", "ILS", "EUR", "AUD", "CAD", "GBP", "DKK", "NOK", "SEK", "BRL", "SGD", "MXN", ….
description	string		Budget description Default: "".
endPeriod	integer (int64)		Fixed budget end date required: true(if budget type is fixed)
growthPerPeriod	number (double)		Periodical growth percentage in recurring budget Default: 0.
metric	string		Budget metric One of: "cost", "amortized_cost". Default: "cost".
name	string		Budget Name.
public	string		One of: "owner", "editor", "viewer".
recipients	array of string		List of emails to notify when reaching alert threshold.
recipientsSlackChannels	array of object		List of Slack channels to notify when reaching alert threshold.
recipientsSlackChannels[].customerId	string
recipientsSlackChannels[].id	string	yes
recipientsSlackChannels[].name	string
recipientsSlackChannels[].shared	boolean
recipientsSlackChannels[].type	string
recipientsSlackChannels[].workspace	string
scopes	array of object		The filters selected define the scope of the budget.
scopes[].id	string	yes	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.
scopes[].type	string	yes	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", ….
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.
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".
scopes[].inverse	boolean		Set to true to exclude the set values. If inverse is omitted, behavior defaults to false.
scopes[].caseInsensitive	boolean		If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise. Default: false.
scopes[].includeNull	boolean		Include rows where the dimension is null. If includeNull is omitted, behavior defaults to false. Default: false.
startPeriod	integer (int64)		Budget start Date
timeInterval	string		Recurring budget interval can be one of: ["day", "week", "month", "quarter", "year"]
type	string		budget type can be one of: ["fixed", "recurring"]
usePrevSpend	boolean		Use the last period's spend as the target amount for recurring budgets Default: false.

Raw JSON schema

{
  "type": "object",
  "description": "Request body for creating or updating a budget.",
  "properties": {
    "alerts": {
      "type": "array",
      "description": "List of up to three thresholds defined as a percentage of the amount.",
      "items": {
        "type": "object",
        "description": "Threshold settings for budget alerts.",
        "properties": {
          "percentage": {
            "type": "number",
            "format": "double"
          }
        }
      }
    },
    "amount": {
      "type": "number",
      "description": "Budget period amount\nrequired: true(if usePrevSpend is false)",
      "format": "double"
    },
    "seasonalAmounts": {
      "type": "array",
      "description": "List of seasonal amounts for recurring budgets with different amounts per period.",
      "items": {
        "type": "number",
        "format": "double"
      }
    },
    "collaborators": {
      "type": "array",
      "description": "List of permitted users to view/edit the report.",
      "items": {
        "type": "object",
        "description": "A user or identity that has access to a resource.",
        "properties": {
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "editor",
              "viewer"
            ]
          }
        }
      }
    },
    "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"
      ]
    },
    "description": {
      "type": "string",
      "description": "Budget description",
      "default": ""
    },
    "endPeriod": {
      "type": "integer",
      "description": "Fixed budget end date\nrequired: true(if budget type is fixed)",
      "format": "int64"
    },
    "growthPerPeriod": {
      "type": "number",
      "description": "Periodical growth percentage in recurring budget",
      "format": "double",
      "default": 0
    },
    "metric": {
      "type": "string",
      "description": "Budget metric",
      "enum": [
        "cost",
        "amortized_cost"
      ],
      "default": "cost"
    },
    "name": {
      "type": "string",
      "description": "Budget Name."
    },
    "public": {
      "type": "string",
      "enum": [
        "owner",
        "editor",
        "viewer"
      ]
    },
    "recipients": {
      "type": "array",
      "description": "List of emails to notify when reaching alert threshold.",
      "items": {
        "type": "string"
      }
    },
    "recipientsSlackChannels": {
      "type": "array",
      "description": "List of Slack channels to notify when reaching alert threshold.",
      "items": {
        "type": "object",
        "description": "Information of a Slack channel for notifications. `customerId` and `workspace` are required unless `shared` is true.",
        "required": [
          "id"
        ],
        "properties": {
          "customerId": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "shared": {
            "type": "boolean"
          },
          "type": {
            "type": "string"
          },
          "workspace": {
            "type": "string"
          }
        }
      }
    },
    "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",
      "description": "Budget start Date",
      "format": "int64"
    },
    "timeInterval": {
      "type": "string",
      "description": "Recurring budget interval can be one of: [\"day\", \"week\", \"month\", \"quarter\", \"year\"]"
    },
    "type": {
      "type": "string",
      "description": "budget type can be one of: [\"fixed\", \"recurring\"]"
    },
    "usePrevSpend": {
      "type": "boolean",
      "description": "Use the last period's spend as the target amount for recurring budgets",
      "default": false
    }
  }
}

Output

OK - Budget updated.

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
alerts	array of object	List of up to three thresholds defined as a percentage of amount.
alerts[].forecastedDate	integer (int64)
alerts[].percentage	number (double)
alerts[].triggered	boolean
amount	number (double)	Budget period amount required: true(if usePrevSpend is false)
seasonalAmounts	array of number (double)	List of seasonal amounts for recurring budgets with different amounts per period.
collaborators	array of object	List of permitted users to view/edit the report.
collaborators[].email	string
collaborators[].role	string	One of: "owner", "editor", "viewer".
createTime	integer (int64)	Creation time (in UNIX timestamp).
currency	string	Currency code for monetary values. One of: "USD", "ILS", "EUR", "AUD", "CAD", "GBP", "DKK", "NOK", "SEK", "BRL", "SGD", "MXN", ….
currentUtilization	number (double)
description	string	Budget description.
endPeriod	integer (int64)	Fixed budget end date (in UNIX timestamp) required: true(if budget type is fixed)
forecastedUtilization	number (double)
growthPerPeriod	number (double)	Periodical growth percentage in recurring budgets. Default: 0.
id	string	budget ID, identifying the report in:path
metric	string	Budget metric - currently fixed to "cost" Default: "cost".
name	string	Budget Name
public	string	Public sharing access level for the budget. One of: "owner", "editor", "viewer".
recipients	array of string	List of emails to notify when reaching alert threshold.
recipientsSlackChannels	array of object	List of Slack channels to notify when reaching alert threshold.
recipientsSlackChannels[].customerId	string
recipientsSlackChannels[].id	string
recipientsSlackChannels[].name	string
recipientsSlackChannels[].shared	boolean
recipientsSlackChannels[].type	string
recipientsSlackChannels[].workspace	string
scopes	array of object	The filters selected define the scope of the budget.
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.
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", ….
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.
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".
scopes[].inverse	boolean	Set to true to exclude the set values. If inverse is omitted, behavior defaults to false.
scopes[].caseInsensitive	boolean	If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise. Default: false.
scopes[].includeNull	boolean	Include rows where the dimension is null. If includeNull is omitted, behavior defaults to false. Default: false.
startPeriod	integer (int64)	Budget start date (in UNIX timestamp).
timeInterval	string	Recurring budget interval can be one of: ["day", "week", "month", "quarter" ,"year"]
type	string	budget type can be one of: ["fixed", "recurring"]
updateTime	integer (int64)	Update time (in UNIX timestamp).
usePrevSpend	boolean	Use the last period's spend as the target amount for recurring budgets. Default: false.

Raw JSON schema

{
  "required": [
    "currency",
    "name",
    "scopes",
    "startPeriod",
    "timeInterval",
    "type"
  ],
  "type": "object",
  "description": "Budget details and runtime metrics.",
  "properties": {
    "alerts": {
      "type": "array",
      "description": "List of up to three thresholds defined as a percentage of amount.",
      "items": {
        "type": "object",
        "description": "Budget alert status details.",
        "properties": {
          "forecastedDate": {
            "type": "integer",
            "format": "int64"
          },
          "percentage": {
            "type": "number",
            "format": "double"
          },
          "triggered": {
            "type": "boolean"
          }
        }
      }
    },
    "amount": {
      "type": "number",
      "description": "Budget period amount\nrequired: true(if usePrevSpend is false)",
      "format": "double"
    },
    "seasonalAmounts": {
      "type": "array",
      "description": "List of seasonal amounts for recurring budgets with different amounts per period.",
      "items": {
        "type": "number",
        "format": "double"
      }
    },
    "collaborators": {
      "type": "array",
      "description": "List of permitted users to view/edit the report.",
      "items": {
        "type": "object",
        "description": "A user or identity that has access to a resource.",
        "properties": {
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "editor",
              "viewer"
            ]
          }
        }
      }
    },
    "createTime": {
      "type": "integer",
      "description": "Creation time (in UNIX timestamp).",
      "format": "int64"
    },
    "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"
      ]
    },
    "currentUtilization": {
      "type": "number",
      "format": "double"
    },
    "description": {
      "type": "string",
      "description": "Budget description."
    },
    "endPeriod": {
      "type": "integer",
      "description": "Fixed budget end date (in UNIX timestamp)\nrequired: true(if budget type is fixed)",
      "format": "int64"
    },
    "forecastedUtilization": {
      "type": "number",
      "format": "double"
    },
    "growthPerPeriod": {
      "type": "number",
      "description": "Periodical growth percentage in recurring budgets.",
      "format": "double",
      "default": 0
    },
    "id": {
      "type": "string",
      "description": "budget ID, identifying the report\nin:path"
    },
    "metric": {
      "type": "string",
      "description": "Budget metric - currently fixed to \"cost\"",
      "default": "cost"
    },
    "name": {
      "type": "string",
      "description": "Budget Name"
    },
    "public": {
      "description": "Public sharing access level for the budget.",
      "type": "string",
      "enum": [
        "owner",
        "editor",
        "viewer"
      ]
    },
    "recipients": {
      "type": "array",
      "description": "List of emails to notify when reaching alert threshold.",
      "items": {
        "type": "string"
      }
    },
    "recipientsSlackChannels": {
      "type": "array",
      "description": "List of Slack channels to notify when reaching alert threshold.",
      "items": {
        "type": "object",
        "description": "Information of a Slack channel for notifications. `customerId` and `workspace` are required unless `shared` is true.",
        "required": [
          "id"
        ],
        "properties": {
          "customerId": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "shared": {
            "type": "boolean"
          },
          "type": {
            "type": "string"
          },
          "workspace": {
            "type": "string"
          }
        }
      }
    },
    "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",
      "description": "Budget start date (in UNIX timestamp).",
      "format": "int64"
    },
    "timeInterval": {
      "type": "string",
      "description": "Recurring budget interval can be one of: [\"day\", \"week\", \"month\", \"quarter\" ,\"year\"]"
    },
    "type": {
      "type": "string",
      "description": "budget type can be one of: [\"fixed\", \"recurring\"]"
    },
    "updateTime": {
      "type": "integer",
      "description": "Update time (in UNIX timestamp).",
      "format": "int64"
    },
    "usePrevSpend": {
      "type": "boolean",
      "description": "Use the last period's spend as the target amount for recurring budgets.",
      "default": false
    }
  }
}

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-budget — Retrieve a budget
• create-budget — Create a budget
• list-budgets — List budgets
• delete-budget — Delete a budget
• API reference: PATCH /analytics/v1/budgets/{id}

Aliases: updatebudget