query
dci query
Runs a report query with the specified configuration without persisting it. Fields that are not populated will use their default values if needed.
Request
Content-Type: application/json
Example
{
"config": {
"dataSource": "billing",
"metrics": [
{
"type": "basic",
"value": "cost"
}
],
"timeRange": {
"amount": 30,
"includeCurrent": false,
"mode": "last",
"unit": "day"
},
"group": [
{
"id": "service_description",
"type": "fixed"
}
],
"timeInterval": "day"
}
}
Schema
{
"type": "object",
"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"
}
}
}
}
Output
OK - The request succeeded.
By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.
| Field | Type | Description |
|---|---|---|
result | object | |
result.schema | array of object | |
result.schema[].id | string | Stable allocation-group ID used to select the allocation dimension in report configurations. Omitted for other report columns. |
result.schema[].name | string | |
result.schema[].type | string | |
result.mlFeatures | array of string | |
result.rows | array of array of string or number or integer | |
result.secondaryRows | array of array of string or number or integer | Secondary time range rows. |
result.forecastRows | array of array of string or number or integer | |
result.cacheHit | boolean | If true, results were fetched from the cache. |
Raw JSON schema
{
"type": "object",
"description": "Results returned when running a report; includes schema and rows.",
"properties": {
"result": {
"type": "object",
"properties": {
"schema": {
"type": "array",
"items": {
"type": "object",
"description": "Schema of a report result column.",
"properties": {
"id": {
"type": "string",
"description": "Stable allocation-group ID used to select the allocation dimension in report configurations. Omitted for other report columns."
},
"name": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
},
"mlFeatures": {
"type": "array",
"items": {
"type": "string",
"enum": [
"increasing",
"decreasing",
"none",
"forecast"
]
}
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"description": "The content of a single cell from a BigQuery result. Can be a string, number, or null.",
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
}
]
}
}
},
"secondaryRows": {
"type": "array",
"description": "Secondary time range rows.",
"items": {
"type": "array",
"items": {
"description": "The content of a single cell from a BigQuery result. Can be a string, number, or null.",
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
}
]
}
}
},
"forecastRows": {
"type": "array",
"items": {
"type": "array",
"items": {
"description": "The content of a single cell from a BigQuery result. Can be a string, number, or null.",
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
}
]
}
}
},
"cacheHit": {
"type": "boolean",
"description": "If true, results were fetched from the cache."
}
}
}
}
}
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. |
| 500 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |