create-budget
dci create-budget
Create a new budget
Request
Content-Type: application/json
Example
{
"name": "monthly-cloud-budget",
"amount": 100,
"currency": "USD",
"usePrevSpend": false,
"type": "recurring",
"timeInterval": "month",
"startPeriod": 1704067200000,
"scopes": [
{
"id": "cloud_provider",
"type": "fixed",
"mode": "is",
"values": [
"amazon-web-services"
]
}
],
"collaborators": [
{
"role": "owner",
}
]
}
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"
}
}
}
},
"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",
"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
Created - New budget created.
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 | |
scope | array of string | List of allocations that defines the budget scope. |
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"
}
}
}
},
"scope": {
"type": "array",
"description": "List of allocations that defines the budget scope.",
"items": {
"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 | 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: createbudget