update-report
dci update-report id
Updates a report with the specified configuration.
Only specified fields will be updated.
Request
Content-Type: application/json
Example
{
"config": {
"timeRange": {
"amount": 1,
"includeCurrent": false,
"mode": "last",
"unit": "month"
},
"timeInterval": "week"
},
"description": "An update via API",
"name": "A new name"
}
Schema
{
"type": "object",
"description": "Partial report object used for updates.",
"properties": {
"config": {
"type": "object",
"description": "Report configuration.",
"properties": {
"metric": {
"deprecated": true,
"description": "Deprecated: Use 'metrics' instead.",
"allOf": [
{
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
}
]
},
"metrics": {
"type": "array",
"description": "The list of metrics to apply to the report. Custom metric can be used only once. Maximum number of metrics is 4.",
"items": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
}
},
"metricFilter": {
"description": "Metric filter to limit report rows by metric value.",
"type": "object",
"required": [
"metric",
"operator",
"values"
],
"properties": {
"metric": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
},
"operator": {
"description": "Comparison operator for filtering metric values. Uses short names (`gt`, `gte`, …).\n`limitByChange.operator` uses SQL-style symbols (`>`, `>=`, …) instead.",
"type": "string",
"enum": [
"gt",
"lt",
"lte",
"gte",
"b",
"nb",
"e",
"ne"
]
},
"values": {
"type": "array",
"items": {
"type": "number",
"format": "double"
}
},
"operand": {
"type": "string",
"description": "Whether the threshold applies to each value (default) or the series total.\nSame field as the DoiT Console metric filter `operand` (`OperandSingleValue` /\n`OperandSeriesTotal`). On input, omitted defaults to `single_value`. GET responses\necho the effective value (`single_value` or `series_total`).",
"enum": [
"single_value",
"series_total"
],
"default": "single_value"
}
},
"example": {
"metric": {
"type": "basic",
"value": "cost"
},
"operator": "gt",
"values": [
50
]
}
},
"limitAggregation": {
"type": "string",
"description": "Controls how rows excluded by limits are rendered. Applies when any limit type is active\n(`metricFilter`, `limitByChange`, or a `group` entry with a `limit`). A report may configure\nat most two of those three limit types — not all three. When `displayValues` is not\n`actuals_only`, this field must be `none` (or omitted, which defaults to `none`).",
"enum": [
"none",
"top",
"all"
],
"default": "none"
},
"limitByChange": {
"description": "Limit by change filter. A report may configure at most two of\n`metricFilter`, `limitByChange`, and top/bottom `group` limits — not all three.",
"type": "object",
"required": [
"metric",
"changeType",
"operator",
"values",
"includeIncompleteData"
],
"properties": {
"metric": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
},
"changeType": {
"type": "string",
"enum": [
"percentage",
"absolute"
]
},
"operator": {
"type": "string",
"description": "Comparison operator for period-over-period deltas.",
"enum": [
">",
">=",
"<",
"<=",
"between",
"not_between"
]
},
"values": {
"type": "array",
"description": "Threshold value(s). Unary operators use one entry; `between` and `not_between`\nrequire two ordered entries.",
"items": {
"type": "number",
"format": "double"
}
},
"includeIncompleteData": {
"type": "boolean",
"description": "When true, keeps rows whose deltas could not be evaluated."
}
},
"example": {
"metric": {
"type": "basic",
"value": "cost"
},
"changeType": "percentage",
"operator": ">=",
"values": [
50
],
"includeIncompleteData": false
}
},
"aggregation": {
"description": "How to aggregate data values in the report.",
"type": "string",
"enum": [
"total",
"percent_total",
"percent_col",
"percent_row",
"total_over_total",
"count"
]
},
"advancedAnalysis": {
"type": "object",
"description": "Advanced analysis options. Each can be set independently.",
"properties": {
"forecast": {
"type": "boolean"
},
"notTrending": {
"type": "boolean"
},
"trendingDown": {
"type": "boolean"
},
"trendingUp": {
"type": "boolean"
}
}
},
"forecastSettings": {
"allOf": [
{
"type": "object",
"description": "Settings for cost forecasting on the report.\nHistorical fields choose which past data the model learns from.\nFuture fields choose how far ahead predicted costs are projected.\nWhen a custom date range is set for a side, it takes precedence over the corresponding interval count.\nfutureCustomDateRange is converted to futureTimeIntervals using the report timeInterval.\nProviding forecastSettings enables forecast (advancedAnalysis.forecast) automatically.\nOn PATCH, omit forecastSettings to leave forecasting unchanged; send forecastSettings: null to clear/disable forecasting\n(also removes the forecast feature flag). An empty object enables forecast with default mode totals.\nInterval counts outside the allowed min/max for the report timeInterval are rejected with a validation error that includes the allowed range.",
"properties": {
"mode": {
"type": "string",
"description": "Forecast granularity mode.",
"enum": [
"totals",
"grouping"
],
"default": "totals"
},
"historicalTimeIntervals": {
"type": "integer",
"format": "int64",
"description": "How many past timeInterval periods of data the model learns from.\nAllowed ranges by timeInterval: hour 2-1000, day 2-500, week 2-100, month 2-36, quarter 2-12, year 2-6."
},
"futureTimeIntervals": {
"type": "integer",
"format": "int64",
"description": "How many future timeInterval periods of predicted costs to project.\nAllowed ranges by timeInterval: hour 1-1000, day 1-100, week 1-52, month 1-12, quarter 1-4, year 1-3."
},
"historicalCustomDateRange": {
"description": "Past date range of billed data the model learns from. Takes precedence over historicalTimeIntervals.",
"allOf": [
{
"type": "object",
"description": "Start and end timestamps in RFC3339 format.",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start timestamp in RFC3339 format.",
"example": "2026-07-10T00:00:00Z"
},
"to": {
"type": "string",
"format": "date-time",
"description": "End timestamp in RFC3339 format.",
"example": "2026-09-30T23:59:59Z"
}
}
}
]
},
"futureCustomDateRange": {
"description": "Date range for how far ahead to project predicted costs. Takes precedence over futureTimeIntervals.\nThe range must resolve to a futureTimeIntervals count within the allowed min/max for the report timeInterval.",
"allOf": [
{
"type": "object",
"description": "Start and end timestamps in RFC3339 format.",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start timestamp in RFC3339 format.",
"example": "2026-07-10T00:00:00Z"
},
"to": {
"type": "string",
"format": "date-time",
"description": "End timestamp in RFC3339 format.",
"example": "2026-09-30T23:59:59Z"
}
}
}
]
}
},
"example": {
"mode": "totals",
"futureCustomDateRange": {
"from": "2026-07-10T00:00:00Z",
"to": "2026-09-30T23:59:59Z"
}
}
}
],
"nullable": true,
"description": "Forecast configuration. On PATCH, omit to preserve existing settings; send null to clear/disable forecasting."
},
"timeInterval": {
"description": "Time interval for grouping data in the report.",
"type": "string",
"enum": [
"hour",
"day",
"dayCumSum",
"week",
"isoweek",
"month",
"quarter",
"year",
"week_day"
]
},
"dimensions": {
"description": "See [Dimensions](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#dimensions).",
"type": "array",
"items": {
"description": "Definition of a report dimension.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The identifier of the dimension."
},
"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."
}
}
},
"example": {
"id": "sku_description",
"type": "fixed"
}
}
},
"timeRange": {
"type": "object",
"description": "Specify a predefined or custom time range for the report.\nFor example, to specify a custom time range of \"last 2 days\", set the mode to `last`, the amount to `2`, and the unit to `day`. If `includeCurrent` is `true`, the range will be yesterday and today; otherwise, the range will be yesterday and the day before yesterday.\nIf \"custom\" type is specified, you need to provide a custom time range in the `customTimeRange` field.",
"properties": {
"amount": {
"description": "Number of time units to include in the time range.",
"maximum": 5000,
"minimum": 0,
"type": "integer",
"format": "int64"
},
"includeCurrent": {
"description": "Whether to include the current time period.",
"type": "boolean"
},
"mode": {
"description": "Time range mode (last N periods, current period, or custom).",
"type": "string",
"enum": [
"last",
"current",
"custom"
]
},
"unit": {
"description": "Time unit for the time range.",
"type": "string",
"enum": [
"day",
"week",
"month",
"quarter",
"year"
]
}
},
"example": {
"amount": 3,
"includeCurrent": false,
"mode": "last",
"unit": "month"
}
},
"secondaryTimeRange": {
"type": "object",
"description": "Secondary time range for comparative reports.",
"properties": {
"amount": {
"description": "Number of periods to shift back.",
"type": "integer",
"format": "int64"
},
"includeCurrent": {
"description": "Whether to align to complete previous periods (full year/quarter/month) vs shifting dates by amount.\n When `true`, selects complete periods (e.g., full previous year Jan 1-Dec 31, not up to today).\n When `false`, shifts dates by amount, which may result in partial periods extending to today.",
"type": "boolean"
},
"unit": {
"description": "Time interval unit for shifting.",
"type": "string",
"enum": [
"day",
"month",
"quarter",
"year"
]
},
"customTimeRange": {
"description": "Custom date range for the secondary time range.",
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start date."
},
"to": {
"type": "string",
"format": "date-time",
"description": "End date."
}
}
}
},
"example": {
"amount": 1,
"includeCurrent": false,
"unit": "year"
}
},
"includePromotionalCredits": {
"type": "boolean",
"description": "Whether to include [promotional credits](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#promotional-credits).\nIf set to **true**, the report must use time interval `month`, `quarter`, or `year`."
},
"includeSubtotals": {
"type": "boolean",
"description": "Whether to include subgroup totals in the report. This option has no impact when reading a report via API.",
"default": false
},
"filters": {
"type": "array",
"description": "The filters to apply to the report.",
"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"
]
}
}
},
"group": {
"type": "array",
"description": "The rows that appear in the tabular format of the report. See [Group by](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#group-by).",
"items": {
"description": "The dimension that defines a row in the report.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dimension ID.",
"example": "service_description"
},
"limit": {
"type": "object",
"description": "To limit the number of results based on ranking. See [Limit by top/bottom](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#limit-by-topbottom).",
"required": [
"metric"
],
"properties": {
"metric": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
},
"sort": {
"description": "Sort order for ranking results.",
"type": "string",
"enum": [
"a_to_z",
"asc",
"desc"
]
},
"value": {
"type": "integer",
"description": "The number of items to show",
"format": "int64"
}
},
"example": {
"value": 3,
"sort": "desc",
"metric": {
"type": "basic",
"value": "cost"
}
}
},
"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."
}
}
},
"example": {
"id": "service_description",
"type": "fixed",
"limit": {
"value": 3,
"sort": "desc",
"metric": {
"type": "basic",
"value": "cost"
}
}
}
}
},
"layout": {
"type": "string",
"description": "Type of visualization or output format.",
"enum": [
"column_chart",
"stacked_column_chart",
"bar_chart",
"stacked_bar_chart",
"line_chart",
"spline_chart",
"area_chart",
"area_spline_chart",
"stacked_area_chart",
"treemap_chart",
"table",
"table_heatmap",
"table_row_heatmap",
"table_col_heatmap",
"csv_export",
"sheets_export"
]
},
"displayValues": {
"type": "string",
"description": "See [View data as (Comparative report)](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#view-as).",
"enum": [
"actuals_only",
"absolute_change",
"percentage_change",
"absolute_and_percentage"
]
},
"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"
]
},
"sortGroups": {
"type": "string",
"default": "asc",
"enum": [
"asc",
"desc",
"a_to_z"
],
"description": "This option has no impact when reading reports via API."
},
"sortDimensions": {
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc",
"a_to_z"
],
"description": "This option has no impact when reading reports via API."
},
"dataSource": {
"type": "string",
"description": "Data source of the report.",
"enum": [
"billing",
"bqlens",
"billing-datahub",
"kubernetes-utilization"
]
},
"splits": {
"type": "array",
"description": "The splits to use in the report.",
"items": {
"type": "object",
"description": "Specification of how to split costs.",
"properties": {
"id": {
"type": "string",
"description": "ID of the field to split."
},
"includeOrigin": {
"type": "boolean",
"description": "Indicate whether to include the origin."
},
"mode": {
"type": "string",
"enum": [
"even",
"custom",
"proportional"
]
},
"origin": {
"type": "object",
"description": "Origin info for cost splitting.",
"properties": {
"id": {
"type": "string",
"description": "ID of the origin."
},
"type": {
"type": "string",
"description": "Type of the origin.",
"example": "attribution",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"gke",
"gke_label",
"unallocated"
]
}
}
},
"targets": {
"type": "array",
"description": "Targets for the split.",
"items": {
"type": "object",
"description": "Target and value of a split definition.",
"properties": {
"id": {
"type": "string",
"description": "ID of the target."
},
"type": {
"type": "string",
"description": "Type of the target.\nIf split type is \"attribution_group\", then target type must be \"attribution\".\nOtherwise split types and target types must be the same.",
"example": "attribution",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"gke",
"gke_label"
]
},
"value": {
"type": "number",
"description": "Percent of the target, represented in float format. E.g. 30% is 0.3. Required only if the Split Mode is custom.",
"format": "double"
}
}
}
},
"type": {
"type": "string",
"description": "Type of the split.",
"example": "attribution_group",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"gke",
"gke_label"
]
}
}
}
},
"displaySettings": {
"type": "object",
"description": "Display settings for the report.",
"properties": {
"themeId": {
"type": "string",
"default": "default",
"description": "Identifier of the theme applied to the report. The reserved\nsentinel `\"default\"` is returned on GET when no theme is stored\nand clears the stored value on PATCH. Omit the field on PATCH\nto leave the stored value unchanged."
},
"dataLabelFontSize": {
"type": "string",
"description": "Font size used for data labels on charts.",
"enum": [
"auto",
"small",
"medium",
"large"
]
},
"axisLabelFontSize": {
"type": "string",
"description": "Font size used for axis labels on charts.",
"enum": [
"auto",
"small",
"medium",
"large"
]
},
"numberScale": {
"type": "string",
"description": "Scale applied to numeric values when rendering the report.",
"enum": [
"auto",
"thousands",
"millions",
"billions",
"raw"
]
},
"decimalPrecision": {
"type": "integer",
"minimum": 0,
"maximum": 8,
"description": "Number of decimal places shown for numeric values."
}
}
},
"customTimeRange": {
"description": "Required when the time range is set to \"custom\".",
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "The start timestamp of the time range in RFC3339 format.",
"example": "2024-03-10T23:00:00Z"
},
"to": {
"type": "string",
"format": "date-time",
"description": "The end timestamp of the time range in RFC3339 format.",
"example": "2024-03-12T23:00:00Z"
}
}
},
"count": {
"type": "object",
"description": "The field to count distinct values of. Only applicable when aggregation is set to \"count\".",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "The field identifier to count distinct values of."
},
"type": {
"type": "string",
"enum": [
"fixed",
"label",
"tag",
"project_label",
"system_label"
],
"description": "The metadata field type."
}
}
}
},
"example": {
"metrics": [
{
"type": "basic",
"value": "cost"
},
{
"type": "basic",
"value": "usage"
},
{
"type": "extended",
"value": "amortized_cost"
}
],
"metricFilter": {
"metric": {
"type": "basic",
"value": "cost"
},
"operator": "nb",
"values": [
-1,
1
],
"operand": "series_total"
},
"limitAggregation": "top",
"limitByChange": {
"metric": {
"type": "basic",
"value": "cost"
},
"changeType": "percentage",
"operator": ">=",
"values": [
50
]
},
"aggregation": "total",
"advancedAnalysis": {
"forecast": false,
"notTrending": false,
"trendingDown": false,
"trendingUp": false
},
"forecastSettings": {
"mode": "totals",
"futureTimeIntervals": 3
},
"timeInterval": "month",
"dimensions": [
{
"id": "year",
"type": "datetime"
},
{
"id": "month",
"type": "datetime"
}
],
"timeRange": {
"amount": 3,
"includeCurrent": false,
"mode": "last",
"unit": "month"
},
"includePromotionalCredits": false,
"includeSubtotals": false,
"filters": [
{
"id": "attribution",
"type": "attribution",
"values": [
"RB8DndcxODriK83IBXXf",
"D7r4znsTj2UC95zGnunW"
],
"inverse": true
},
{
"id": "cloud_provider",
"type": "fixed",
"values": [
"amazon-web-services",
"google-cloud",
"microsoft-azure"
]
}
],
"group": [
{
"id": "service_description",
"limit": {
"metric": {
"type": "basic",
"value": "cost"
},
"sort": "a_to_z",
"value": 0
},
"type": "fixed"
}
],
"layout": "table",
"displayValues": "actuals_only",
"currency": "USD",
"sortGroups": "a_to_z",
"sortDimensions": "a_to_z",
"dataSource": "billing"
}
},
"description": {
"type": "string",
"description": "Report description"
},
"name": {
"type": "string",
"description": "Report name"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of label IDs assigned to the report"
},
"folderId": {
"type": "string",
"description": "Identifier of the folder that contains the report. Set to \"root\" if the report is at the top level (not in a folder).",
"default": "root",
"example": "root"
}
},
"example": {
"config": {
"timeRange": {
"amount": 1,
"includeCurrent": false,
"mode": "last",
"unit": "month"
},
"timeInterval": "week"
},
"description": "An update via API",
"name": "A new name"
}
}
Output
OK - Report 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 |
|---|---|---|
id | string | Report ID. |
name | string | Report name. |
description | string | Report description. |
type | string | Report type. One of: "custom", "preset", "managed". |
config | object | Report configuration. |
config.metric | object | Deprecated: Use 'metrics' instead. |
config.metric.type | string | Type of metric to use. One of: "basic", "custom", "extended". |
config.metric.value | string | For basic metrics, the value can be one of: ["cost", "usage", "savings"] If using custom metrics, the value must refer to an existing custom metric ID. |
config.metrics | array of object | The list of metrics to apply to the report. Custom metric can be used only once. Maximum number of metrics is 4. |
config.metrics[].type | string | Type of metric to use. One of: "basic", "custom", "extended". |
config.metrics[].value | string | For basic metrics, the value can be one of: ["cost", "usage", "savings"] If using custom metrics, the value must refer to an existing custom metric ID. |
config.metricFilter | object | Metric filter to limit report rows by metric value. |
config.metricFilter.metric | object | Metric selector used in reports and filters. |
config.metricFilter.metric.type | string | Type of metric to use. One of: "basic", "custom", "extended". |
config.metricFilter.metric.value | string | For basic metrics, the value can be one of: ["cost", "usage", "savings"] If using custom metrics, the value must refer to an existing custom metric ID. |
config.metricFilter.operator | string | Comparison operator for filtering metric values. Uses short names (gt, gte, …). limitByChange.operator uses SQL-style symbols (>, >=, …) instead. One of: "gt", "lt", "lte", "gte", "b", "nb", "e", "ne". |
config.metricFilter.values | array of number (double) | |
config.metricFilter.operand | string | Whether the threshold applies to each value (default) or the series total. Same field as the DoiT Console metric filter operand (OperandSingleValue / OperandSeriesTotal). On input, omitted defaults to single_value. GET responses echo the effective value (single_value or series_total). One of: "single_value", "series_total". Default: "single_value". |
config.limitAggregation | string | Controls how rows excluded by limits are rendered. Applies when any limit type is active (metricFilter, limitByChange, or a group entry with a limit). A report may configure at most two of those three limit types — not all three. When displayValues is not actuals_only, this field must be none (or omitted, which defaults to none). One of: "none", "top", "all". Default: "none". |
config.limitByChange | object | Limit by change filter. A report may configure at most two of metricFilter, limitByChange, and top/bottom group limits — not all three. |
config.limitByChange.metric | object | Metric selector used in reports and filters. |
config.limitByChange.metric.type | string | Type of metric to use. One of: "basic", "custom", "extended". |
config.limitByChange.metric.value | string | For basic metrics, the value can be one of: ["cost", "usage", "savings"] If using custom metrics, the value must refer to an existing custom metric ID. |
config.limitByChange.changeType | string | One of: "percentage", "absolute". |
config.limitByChange.operator | string | Comparison operator for period-over-period deltas. One of: ">", ">=", "<", "<=", "between", "not_between". |
config.limitByChange.values | array of number (double) | Threshold value(s). Unary operators use one entry; between and not_between require two ordered entries. |
config.limitByChange.includeIncompleteData | boolean | When true, keeps rows whose deltas could not be evaluated. |
config.aggregation | string | How to aggregate data values in the report. One of: "total", "percent_total", "percent_col", "percent_row", "total_over_total", "count". |
config.advancedAnalysis | object | Advanced analysis options. Each can be set independently. |
config.advancedAnalysis.forecast | boolean | |
config.advancedAnalysis.notTrending | boolean | |
config.advancedAnalysis.trendingDown | boolean | |
config.advancedAnalysis.trendingUp | boolean | |
config.forecastSettings | object | Forecast configuration. On PATCH, omit to preserve existing settings; send null to clear/disable forecasting. |
config.forecastSettings.mode | string | Forecast granularity mode. One of: "totals", "grouping". Default: "totals". |
config.forecastSettings.historicalTimeIntervals | integer (int64) | How many past timeInterval periods of data the model learns from. Allowed ranges by timeInterval: hour 2-1000, day 2-500, week 2-100, month 2-36, quarter 2-12, year 2-6. |
config.forecastSettings.futureTimeIntervals | integer (int64) | How many future timeInterval periods of predicted costs to project. Allowed ranges by timeInterval: hour 1-1000, day 1-100, week 1-52, month 1-12, quarter 1-4, year 1-3. |
config.forecastSettings.historicalCustomDateRange | object | Past date range of billed data the model learns from. Takes precedence over historicalTimeIntervals. |
config.forecastSettings.historicalCustomDateRange.from | string (date-time) | Start timestamp in RFC3339 format. |
config.forecastSettings.historicalCustomDateRange.to | string (date-time) | End timestamp in RFC3339 format. |
config.forecastSettings.futureCustomDateRange | object | Date range for how far ahead to project predicted costs. Takes precedence over futureTimeIntervals. The range must resolve to a futureTimeIntervals count within the allowed min/max for the report timeInterval. |
config.forecastSettings.futureCustomDateRange.from | string (date-time) | Start timestamp in RFC3339 format. |
config.forecastSettings.futureCustomDateRange.to | string (date-time) | End timestamp in RFC3339 format. |
config.timeInterval | string | Time interval for grouping data in the report. One of: "hour", "day", "dayCumSum", "week", "isoweek", "month", "quarter", "year", "week_day". |
config.dimensions | array of object | See Dimensions. |
config.dimensions[].id | string | The identifier of the dimension. |
config.dimensions[].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", …. |
config.timeRange | object | Specify a predefined or custom time range for the report. For example, to specify a custom time range of "last 2 days", set the mode to last, the amount to 2, and the unit to day. If includeCurrent is true, the range will be yesterday and today; otherwise, the range will be yesterday and the day before yesterday. If "custom" type is specified, you need to provide a custom time range in the customTimeRange field. |
config.timeRange.amount | integer (int64) | Number of time units to include in the time range. |
config.timeRange.includeCurrent | boolean | Whether to include the current time period. |
config.timeRange.mode | string | Time range mode (last N periods, current period, or custom). One of: "last", "current", "custom". |
config.timeRange.unit | string | Time unit for the time range. One of: "day", "week", "month", "quarter", "year". |
config.secondaryTimeRange | object | Secondary time range for comparative reports. |
config.secondaryTimeRange.amount | integer (int64) | Number of periods to shift back. |
config.secondaryTimeRange.includeCurrent | boolean | Whether to align to complete previous periods (full year/quarter/month) vs shifting dates by amount. When true, selects complete periods (e.g., full previous year Jan 1-Dec 31, not up to today). When false, shifts dates by amount, which may result in partial periods extending to today. |
config.secondaryTimeRange.unit | string | Time interval unit for shifting. One of: "day", "month", "quarter", "year". |
config.secondaryTimeRange.customTimeRange | object | Custom date range for the secondary time range. |
config.secondaryTimeRange.customTimeRange.from | string (date-time) | Start date. |
config.secondaryTimeRange.customTimeRange.to | string (date-time) | End date. |
config.includePromotionalCredits | boolean | Whether to include promotional credits. If set to true, the report must use time interval month, quarter, or year. |
config.includeSubtotals | boolean | Whether to include subgroup totals in the report. This option has no impact when reading a report via API. Default: false. |
config.filters | array of object | The filters to apply to the report. |
config.filters[].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. |
config.filters[].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", …. |
config.filters[].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. |
config.filters[].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". |
config.filters[].inverse | boolean | Set to true to exclude the set values. If inverse is omitted, behavior defaults to false. |
config.filters[].caseInsensitive | boolean | If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise. Default: false. |
config.filters[].includeNull | boolean | Include rows where the dimension is null. If includeNull is omitted, behavior defaults to false. Default: false. |
config.group | array of object | The rows that appear in the tabular format of the report. See Group by. |
config.group[].id | string | Dimension ID. |
config.group[].limit | object | To limit the number of results based on ranking. See Limit by top/bottom. |
config.group[].limit.metric | object | Metric selector used in reports and filters. Nested fields omitted — see the raw JSON schema. |
config.group[].limit.sort | string | Sort order for ranking results. One of: "a_to_z", "asc", "desc". |
config.group[].limit.value | integer (int64) | The number of items to show |
config.group[].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", …. |
config.layout | string | Type of visualization or output format. One of: "column_chart", "stacked_column_chart", "bar_chart", "stacked_bar_chart", "line_chart", "spline_chart", "area_chart", "area_spline_chart", "stacked_area_chart", "treemap_chart", "table", "table_heatmap", …. |
config.displayValues | string | See View data as (Comparative report). One of: "actuals_only", "absolute_change", "percentage_change", "absolute_and_percentage". |
config.currency | string | Currency code for monetary values. One of: "USD", "ILS", "EUR", "AUD", "CAD", "GBP", "DKK", "NOK", "SEK", "BRL", "SGD", "MXN", …. |
config.sortGroups | string | This option has no impact when reading reports via API. One of: "asc", "desc", "a_to_z". Default: "asc". |
config.sortDimensions | string | This option has no impact when reading reports via API. One of: "asc", "desc", "a_to_z". Default: "desc". |
config.dataSource | string | Data source of the report. One of: "billing", "bqlens", "billing-datahub", "kubernetes-utilization". |
config.splits | array of object | The splits to use in the report. |
config.splits[].id | string | ID of the field to split. |
config.splits[].includeOrigin | boolean | Indicate whether to include the origin. |
config.splits[].mode | string | One of: "even", "custom", "proportional". |
config.splits[].origin | object | Origin info for cost splitting. |
config.splits[].origin.id | string | ID of the origin. |
config.splits[].origin.type | string | Type of the origin. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "attribution", "attribution_group", "gke", "gke_label", "unallocated". |
config.splits[].targets | array of object | Targets for the split. |
config.splits[].targets[].id | string | ID of the target. |
config.splits[].targets[].type | string | Type of the target. If split type is "attribution_group", then target type must be "attribution". Otherwise split types and target types must be the same. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "attribution", "attribution_group", "gke", "gke_label". |
config.splits[].targets[].value | number (double) | Percent of the target, represented in float format. E.g. 30% is 0.3. Required only if the Split Mode is custom. |
config.splits[].type | string | Type of the split. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "attribution", "attribution_group", "gke", "gke_label". |
config.displaySettings | object | Display settings for the report. |
config.displaySettings.themeId | string | Identifier of the theme applied to the report. The reserved sentinel "default" is returned on GET when no theme is stored and clears the stored value on PATCH. Omit the field on PATCH to leave the stored value unchanged. Default: "default". |
config.displaySettings.dataLabelFontSize | string | Font size used for data labels on charts. One of: "auto", "small", "medium", "large". |
config.displaySettings.axisLabelFontSize | string | Font size used for axis labels on charts. One of: "auto", "small", "medium", "large". |
config.displaySettings.numberScale | string | Scale applied to numeric values when rendering the report. One of: "auto", "thousands", "millions", "billions", "raw". |
config.displaySettings.decimalPrecision | integer | Number of decimal places shown for numeric values. |
注意
The field list above is truncated. Expand the raw JSON schema below for the full structure.
Raw JSON schema
{
"required": [
"name"
],
"type": "object",
"description": "Configuration and metadata of a stored report.",
"properties": {
"id": {
"type": "string",
"description": "Report ID."
},
"name": {
"type": "string",
"description": "Report name."
},
"description": {
"type": "string",
"description": "Report description."
},
"type": {
"type": "string",
"description": "Report type.",
"enum": [
"custom",
"preset",
"managed"
]
},
"config": {
"type": "object",
"description": "Report configuration.",
"properties": {
"metric": {
"deprecated": true,
"description": "Deprecated: Use 'metrics' instead.",
"allOf": [
{
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
}
]
},
"metrics": {
"type": "array",
"description": "The list of metrics to apply to the report. Custom metric can be used only once. Maximum number of metrics is 4.",
"items": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
}
},
"metricFilter": {
"description": "Metric filter to limit report rows by metric value.",
"type": "object",
"required": [
"metric",
"operator",
"values"
],
"properties": {
"metric": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
},
"operator": {
"description": "Comparison operator for filtering metric values. Uses short names (`gt`, `gte`, …).\n`limitByChange.operator` uses SQL-style symbols (`>`, `>=`, …) instead.",
"type": "string",
"enum": [
"gt",
"lt",
"lte",
"gte",
"b",
"nb",
"e",
"ne"
]
},
"values": {
"type": "array",
"items": {
"type": "number",
"format": "double"
}
},
"operand": {
"type": "string",
"description": "Whether the threshold applies to each value (default) or the series total.\nSame field as the DoiT Console metric filter `operand` (`OperandSingleValue` /\n`OperandSeriesTotal`). On input, omitted defaults to `single_value`. GET responses\necho the effective value (`single_value` or `series_total`).",
"enum": [
"single_value",
"series_total"
],
"default": "single_value"
}
},
"example": {
"metric": {
"type": "basic",
"value": "cost"
},
"operator": "gt",
"values": [
50
]
}
},
"limitAggregation": {
"type": "string",
"description": "Controls how rows excluded by limits are rendered. Applies when any limit type is active\n(`metricFilter`, `limitByChange`, or a `group` entry with a `limit`). A report may configure\nat most two of those three limit types — not all three. When `displayValues` is not\n`actuals_only`, this field must be `none` (or omitted, which defaults to `none`).",
"enum": [
"none",
"top",
"all"
],
"default": "none"
},
"limitByChange": {
"description": "Limit by change filter. A report may configure at most two of\n`metricFilter`, `limitByChange`, and top/bottom `group` limits — not all three.",
"type": "object",
"required": [
"metric",
"changeType",
"operator",
"values",
"includeIncompleteData"
],
"properties": {
"metric": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
},
"changeType": {
"type": "string",
"enum": [
"percentage",
"absolute"
]
},
"operator": {
"type": "string",
"description": "Comparison operator for period-over-period deltas.",
"enum": [
">",
">=",
"<",
"<=",
"between",
"not_between"
]
},
"values": {
"type": "array",
"description": "Threshold value(s). Unary operators use one entry; `between` and `not_between`\nrequire two ordered entries.",
"items": {
"type": "number",
"format": "double"
}
},
"includeIncompleteData": {
"type": "boolean",
"description": "When true, keeps rows whose deltas could not be evaluated."
}
},
"example": {
"metric": {
"type": "basic",
"value": "cost"
},
"changeType": "percentage",
"operator": ">=",
"values": [
50
],
"includeIncompleteData": false
}
},
"aggregation": {
"description": "How to aggregate data values in the report.",
"type": "string",
"enum": [
"total",
"percent_total",
"percent_col",
"percent_row",
"total_over_total",
"count"
]
},
"advancedAnalysis": {
"type": "object",
"description": "Advanced analysis options. Each can be set independently.",
"properties": {
"forecast": {
"type": "boolean"
},
"notTrending": {
"type": "boolean"
},
"trendingDown": {
"type": "boolean"
},
"trendingUp": {
"type": "boolean"
}
}
},
"forecastSettings": {
"allOf": [
{
"type": "object",
"description": "Settings for cost forecasting on the report.\nHistorical fields choose which past data the model learns from.\nFuture fields choose how far ahead predicted costs are projected.\nWhen a custom date range is set for a side, it takes precedence over the corresponding interval count.\nfutureCustomDateRange is converted to futureTimeIntervals using the report timeInterval.\nProviding forecastSettings enables forecast (advancedAnalysis.forecast) automatically.\nOn PATCH, omit forecastSettings to leave forecasting unchanged; send forecastSettings: null to clear/disable forecasting\n(also removes the forecast feature flag). An empty object enables forecast with default mode totals.\nInterval counts outside the allowed min/max for the report timeInterval are rejected with a validation error that includes the allowed range.",
"properties": {
"mode": {
"type": "string",
"description": "Forecast granularity mode.",
"enum": [
"totals",
"grouping"
],
"default": "totals"
},
"historicalTimeIntervals": {
"type": "integer",
"format": "int64",
"description": "How many past timeInterval periods of data the model learns from.\nAllowed ranges by timeInterval: hour 2-1000, day 2-500, week 2-100, month 2-36, quarter 2-12, year 2-6."
},
"futureTimeIntervals": {
"type": "integer",
"format": "int64",
"description": "How many future timeInterval periods of predicted costs to project.\nAllowed ranges by timeInterval: hour 1-1000, day 1-100, week 1-52, month 1-12, quarter 1-4, year 1-3."
},
"historicalCustomDateRange": {
"description": "Past date range of billed data the model learns from. Takes precedence over historicalTimeIntervals.",
"allOf": [
{
"type": "object",
"description": "Start and end timestamps in RFC3339 format.",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start timestamp in RFC3339 format.",
"example": "2026-07-10T00:00:00Z"
},
"to": {
"type": "string",
"format": "date-time",
"description": "End timestamp in RFC3339 format.",
"example": "2026-09-30T23:59:59Z"
}
}
}
]
},
"futureCustomDateRange": {
"description": "Date range for how far ahead to project predicted costs. Takes precedence over futureTimeIntervals.\nThe range must resolve to a futureTimeIntervals count within the allowed min/max for the report timeInterval.",
"allOf": [
{
"type": "object",
"description": "Start and end timestamps in RFC3339 format.",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start timestamp in RFC3339 format.",
"example": "2026-07-10T00:00:00Z"
},
"to": {
"type": "string",
"format": "date-time",
"description": "End timestamp in RFC3339 format.",
"example": "2026-09-30T23:59:59Z"
}
}
}
]
}
},
"example": {
"mode": "totals",
"futureCustomDateRange": {
"from": "2026-07-10T00:00:00Z",
"to": "2026-09-30T23:59:59Z"
}
}
}
],
"nullable": true,
"description": "Forecast configuration. On PATCH, omit to preserve existing settings; send null to clear/disable forecasting."
},
"timeInterval": {
"description": "Time interval for grouping data in the report.",
"type": "string",
"enum": [
"hour",
"day",
"dayCumSum",
"week",
"isoweek",
"month",
"quarter",
"year",
"week_day"
]
},
"dimensions": {
"description": "See [Dimensions](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#dimensions).",
"type": "array",
"items": {
"description": "Definition of a report dimension.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The identifier of the dimension."
},
"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."
}
}
},
"example": {
"id": "sku_description",
"type": "fixed"
}
}
},
"timeRange": {
"type": "object",
"description": "Specify a predefined or custom time range for the report.\nFor example, to specify a custom time range of \"last 2 days\", set the mode to `last`, the amount to `2`, and the unit to `day`. If `includeCurrent` is `true`, the range will be yesterday and today; otherwise, the range will be yesterday and the day before yesterday.\nIf \"custom\" type is specified, you need to provide a custom time range in the `customTimeRange` field.",
"properties": {
"amount": {
"description": "Number of time units to include in the time range.",
"maximum": 5000,
"minimum": 0,
"type": "integer",
"format": "int64"
},
"includeCurrent": {
"description": "Whether to include the current time period.",
"type": "boolean"
},
"mode": {
"description": "Time range mode (last N periods, current period, or custom).",
"type": "string",
"enum": [
"last",
"current",
"custom"
]
},
"unit": {
"description": "Time unit for the time range.",
"type": "string",
"enum": [
"day",
"week",
"month",
"quarter",
"year"
]
}
},
"example": {
"amount": 3,
"includeCurrent": false,
"mode": "last",
"unit": "month"
}
},
"secondaryTimeRange": {
"type": "object",
"description": "Secondary time range for comparative reports.",
"properties": {
"amount": {
"description": "Number of periods to shift back.",
"type": "integer",
"format": "int64"
},
"includeCurrent": {
"description": "Whether to align to complete previous periods (full year/quarter/month) vs shifting dates by amount.\n When `true`, selects complete periods (e.g., full previous year Jan 1-Dec 31, not up to today).\n When `false`, shifts dates by amount, which may result in partial periods extending to today.",
"type": "boolean"
},
"unit": {
"description": "Time interval unit for shifting.",
"type": "string",
"enum": [
"day",
"month",
"quarter",
"year"
]
},
"customTimeRange": {
"description": "Custom date range for the secondary time range.",
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "Start date."
},
"to": {
"type": "string",
"format": "date-time",
"description": "End date."
}
}
}
},
"example": {
"amount": 1,
"includeCurrent": false,
"unit": "year"
}
},
"includePromotionalCredits": {
"type": "boolean",
"description": "Whether to include [promotional credits](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#promotional-credits).\nIf set to **true**, the report must use time interval `month`, `quarter`, or `year`."
},
"includeSubtotals": {
"type": "boolean",
"description": "Whether to include subgroup totals in the report. This option has no impact when reading a report via API.",
"default": false
},
"filters": {
"type": "array",
"description": "The filters to apply to the report.",
"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"
]
}
}
},
"group": {
"type": "array",
"description": "The rows that appear in the tabular format of the report. See [Group by](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#group-by).",
"items": {
"description": "The dimension that defines a row in the report.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dimension ID.",
"example": "service_description"
},
"limit": {
"type": "object",
"description": "To limit the number of results based on ranking. See [Limit by top/bottom](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#limit-by-topbottom).",
"required": [
"metric"
],
"properties": {
"metric": {
"description": "Metric selector used in reports and filters.",
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"description": "Type of metric to use.",
"type": "string",
"enum": [
"basic",
"custom",
"extended"
]
},
"value": {
"type": "string",
"description": "For basic metrics, the value can be one of: [\"cost\", \"usage\", \"savings\"]\nIf using custom metrics, the value must refer to an existing custom metric ID."
}
},
"example": {
"type": "basic",
"value": "cost"
}
},
"sort": {
"description": "Sort order for ranking results.",
"type": "string",
"enum": [
"a_to_z",
"asc",
"desc"
]
},
"value": {
"type": "integer",
"description": "The number of items to show",
"format": "int64"
}
},
"example": {
"value": 3,
"sort": "desc",
"metric": {
"type": "basic",
"value": "cost"
}
}
},
"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."
}
}
},
"example": {
"id": "service_description",
"type": "fixed",
"limit": {
"value": 3,
"sort": "desc",
"metric": {
"type": "basic",
"value": "cost"
}
}
}
}
},
"layout": {
"type": "string",
"description": "Type of visualization or output format.",
"enum": [
"column_chart",
"stacked_column_chart",
"bar_chart",
"stacked_bar_chart",
"line_chart",
"spline_chart",
"area_chart",
"area_spline_chart",
"stacked_area_chart",
"treemap_chart",
"table",
"table_heatmap",
"table_row_heatmap",
"table_col_heatmap",
"csv_export",
"sheets_export"
]
},
"displayValues": {
"type": "string",
"description": "See [View data as (Comparative report)](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#view-as).",
"enum": [
"actuals_only",
"absolute_change",
"percentage_change",
"absolute_and_percentage"
]
},
"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"
]
},
"sortGroups": {
"type": "string",
"default": "asc",
"enum": [
"asc",
"desc",
"a_to_z"
],
"description": "This option has no impact when reading reports via API."
},
"sortDimensions": {
"type": "string",
"default": "desc",
"enum": [
"asc",
"desc",
"a_to_z"
],
"description": "This option has no impact when reading reports via API."
},
"dataSource": {
"type": "string",
"description": "Data source of the report.",
"enum": [
"billing",
"bqlens",
"billing-datahub",
"kubernetes-utilization"
]
},
"splits": {
"type": "array",
"description": "The splits to use in the report.",
"items": {
"type": "object",
"description": "Specification of how to split costs.",
"properties": {
"id": {
"type": "string",
"description": "ID of the field to split."
},
"includeOrigin": {
"type": "boolean",
"description": "Indicate whether to include the origin."
},
"mode": {
"type": "string",
"enum": [
"even",
"custom",
"proportional"
]
},
"origin": {
"type": "object",
"description": "Origin info for cost splitting.",
"properties": {
"id": {
"type": "string",
"description": "ID of the origin."
},
"type": {
"type": "string",
"description": "Type of the origin.",
"example": "attribution",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"gke",
"gke_label",
"unallocated"
]
}
}
},
"targets": {
"type": "array",
"description": "Targets for the split.",
"items": {
"type": "object",
"description": "Target and value of a split definition.",
"properties": {
"id": {
"type": "string",
"description": "ID of the target."
},
"type": {
"type": "string",
"description": "Type of the target.\nIf split type is \"attribution_group\", then target type must be \"attribution\".\nOtherwise split types and target types must be the same.",
"example": "attribution",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"gke",
"gke_label"
]
},
"value": {
"type": "number",
"description": "Percent of the target, represented in float format. E.g. 30% is 0.3. Required only if the Split Mode is custom.",
"format": "double"
}
}
}
},
"type": {
"type": "string",
"description": "Type of the split.",
"example": "attribution_group",
"enum": [
"datetime",
"fixed",
"optional",
"label",
"tag",
"project_label",
"system_label",
"attribution",
"attribution_group",
"gke",
"gke_label"
]
}
}
}
},
"displaySettings": {
"type": "object",
"description": "Display settings for the report.",
"properties": {
"themeId": {
"type": "string",
"default": "default",
"description": "Identifier of the theme applied to the report. The reserved\nsentinel `\"default\"` is returned on GET when no theme is stored\nand clears the stored value on PATCH. Omit the field on PATCH\nto leave the stored value unchanged."
},
"dataLabelFontSize": {
"type": "string",
"description": "Font size used for data labels on charts.",
"enum": [
"auto",
"small",
"medium",
"large"
]
},
"axisLabelFontSize": {
"type": "string",
"description": "Font size used for axis labels on charts.",
"enum": [
"auto",
"small",
"medium",
"large"
]
},
"numberScale": {
"type": "string",
"description": "Scale applied to numeric values when rendering the report.",
"enum": [
"auto",
"thousands",
"millions",
"billions",
"raw"
]
},
"decimalPrecision": {
"type": "integer",
"minimum": 0,
"maximum": 8,
"description": "Number of decimal places shown for numeric values."
}
}
},
"customTimeRange": {
"description": "Required when the time range is set to \"custom\".",
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time",
"description": "The start timestamp of the time range in RFC3339 format.",
"example": "2024-03-10T23:00:00Z"
},
"to": {
"type": "string",
"format": "date-time",
"description": "The end timestamp of the time range in RFC3339 format.",
"example": "2024-03-12T23:00:00Z"
}
}
},
"count": {
"type": "object",
"description": "The field to count distinct values of. Only applicable when aggregation is set to \"count\".",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "The field identifier to count distinct values of."
},
"type": {
"type": "string",
"enum": [
"fixed",
"label",
"tag",
"project_label",
"system_label"
],
"description": "The metadata field type."
}
}
}
},
"example": {
"metrics": [
{
"type": "basic",
"value": "cost"
},
{
"type": "basic",
"value": "usage"
},
{
"type": "extended",
"value": "amortized_cost"
}
],
"metricFilter": {
"metric": {
"type": "basic",
"value": "cost"
},
"operator": "nb",
"values": [
-1,
1
],
"operand": "series_total"
},
"limitAggregation": "top",
"limitByChange": {
"metric": {
"type": "basic",
"value": "cost"
},
"changeType": "percentage",
"operator": ">=",
"values": [
50
]
},
"aggregation": "total",
"advancedAnalysis": {
"forecast": false,
"notTrending": false,
"trendingDown": false,
"trendingUp": false
},
"forecastSettings": {
"mode": "totals",
"futureTimeIntervals": 3
},
"timeInterval": "month",
"dimensions": [
{
"id": "year",
"type": "datetime"
},
{
"id": "month",
"type": "datetime"
}
],
"timeRange": {
"amount": 3,
"includeCurrent": false,
"mode": "last",
"unit": "month"
},
"includePromotionalCredits": false,
"includeSubtotals": false,
"filters": [
{
"id": "attribution",
"type": "attribution",
"values": [
"RB8DndcxODriK83IBXXf",
"D7r4znsTj2UC95zGnunW"
],
"inverse": true
},
{
"id": "cloud_provider",
"type": "fixed",
"values": [
"amazon-web-services",
"google-cloud",
"microsoft-azure"
]
}
],
"group": [
{
"id": "service_description",
"limit": {
"metric": {
"type": "basic",
"value": "cost"
},
"sort": "a_to_z",
"value": 0
},
"type": "fixed"
}
],
"layout": "table",
"displayValues": "actuals_only",
"currency": "USD",
"sortGroups": "a_to_z",
"sortDimensions": "a_to_z",
"dataSource": "billing"
}
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of label IDs assigned to the report"
},
"folderId": {
"type": "string",
"description": "Identifier of the folder that contains the report. Set to \"root\" if the report is at the top level (not in a folder).",
"default": "root",
"example": "root"
}
}
}
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. |
| 500 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Aliases: updatereport