---
title: Execute detailed cost analytics query with breakdowns
slug: reference/execute-detailed-cost-analytics-query-with-breakdowns
docTags:
createdAt: 2025-07-03T16:20:35.017Z
---
{
"id": "IIg3Qtdy5DwEVQoOsJR6u",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/business-unit/usage-cost/query",
"servers": [
{
"url": "https://app.amberflo.io/business-unit/usage-cost/query"
}
],
"name": "Execute detailed cost analytics query with breakdowns",
"description": "Execute detailed analytics queries for business unit usage, billing costs, and chargeback calculations across cloud resources. Returns comprehensive time series data with detailed breakdowns, supporting aggregation by time intervals, filtering by cloud dimensions, grouping by business unit attributes, and forecasting future costs based on historical usage patterns.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "optional",
"name": "body",
"type": "object",
"description": "",
"customType": "business_unit.usage_cost.BusinessUnitUsageCostQuery.in",
"schema": [
{
"name": "aggregation",
"kind": "required",
"type": "string",
"description": "Mathematical aggregation function for combining data values. Currently only SUM is supported for totaling numeric metrics across time periods and dimensional groupings.",
"modelRef": "#/components/schemas/focus.analytics.AggregationType.in",
"customType": "focus.analytics.AggregationType.in",
"schema": []
},
{
"name": "timeGroupingInterval",
"kind": "optional",
"type": "string",
"description": "Time granularity for data aggregation and bucketing. HOUR creates hourly buckets, DAY creates daily buckets, WEEK creates weekly buckets starting Monday, MONTH creates monthly buckets. Each defines timestamp resolution and bucket size for time-series data.",
"modelRef": "#/components/schemas/focus.analytics.AggregationInterval.in",
"customType": "focus.analytics.AggregationInterval.in",
"schema": []
},
{
"name": "timeRange",
"kind": "required",
"type": "object",
"description": "Time period for which to execute the query.",
"modelRef": "#/components/schemas/focus.analytics.TimeRange.in",
"customType": "focus.analytics.TimeRange.in",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Start time for analytics query in Unix timestamp seconds. Inclusive lower bound for time range filtering.",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "End time for analytics query in Unix timestamp seconds. Exclusive upper bound for time range filtering.",
"example": 0
}
]
},
{
"name": "filter",
"kind": "optional",
"type": "map",
"description": "",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "groupBy",
"kind": "optional",
"type": "array",
"description": "",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "page",
"kind": "optional",
"type": "object",
"description": "Pagination specification for limiting result set size. Both number and size are required to enable proper pagination through large datasets.",
"modelRef": "#/components/schemas/focus.analytics.PageSpec.in",
"customType": "focus.analytics.PageSpec.in",
"schema": [
{
"name": "number",
"kind": "required",
"type": "integer",
"description": "Page number for pagination starting from 1. Must be at least 1 for valid pagination requests.",
"example": 0
},
{
"name": "size",
"kind": "required",
"type": "integer",
"description": "Number of records per page. Must be between 1 and 1000 inclusive for performance limits.",
"example": 0
}
]
},
{
"name": "limit",
"kind": "optional",
"type": "integer",
"description": "",
"example": 0
},
{
"name": "sort",
"kind": "optional",
"type": "object",
"description": "Sort specification for ordering query results. Defines both the fields to sort by and the sort direction, enabling consistent result ordering.",
"modelRef": "#/components/schemas/focus.analytics.SortSpec.in",
"customType": "focus.analytics.SortSpec.in",
"schema": [
{
"name": "isAscending",
"kind": "optional",
"type": "boolean",
"description": "Sort direction flag where true indicates ascending order and false indicates descending order. Defaults to false for descending.",
"example": ""
},
{
"name": "sortBy",
"kind": "required",
"type": "array",
"description": "Array of field names to sort by in priority order. Must contain at least one field and cannot have duplicates.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
}
]
},
{
"name": "usageItems",
"kind": "required",
"type": "array",
"description": "Which metrics to include in the result.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "summaryOnly",
"kind": "optional",
"type": "boolean",
"description": "Set to false to only compute the group totals and omit the values time series.",
"example": ""
},
{
"name": "forecast",
"kind": "optional",
"type": "object",
"description": "Forecast future usage. Currently, it uses a linear model.",
"modelRef": "#/components/schemas/focus.analytics.ForecastOptions.in",
"customType": "focus.analytics.ForecastOptions.in",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp for forecast period start using linear regression model on historical data.\n\n**Important note:** Defaults to query end time to avoid training on partial current period data.\n",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp for forecast period end defining the prediction time range boundary.\n\n**Constraint:** Must be less than one year from current time for realistic forecasting accuracy.\n",
"example": 0
}
]
},
{
"name": "subTotalBy",
"kind": "optional",
"type": "string",
"description": "",
"example": ""
}
],
"modelRef": "#/components/schemas/business_unit.usage_cost.BusinessUnitUsageCostQuery.in",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Successful request",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "",
"customType": "business_unit.usage_cost.DetailedBusinessUnitUsageCostQueryResult.out",
"schema": [
{
"name": "pageMetadata",
"kind": "optional",
"type": "object",
"description": "**Analytics pagination metadata for result navigation**\n\n**Important note:** Provides pagination context for analytics query results with page navigation details\n\n**Technical details:**\n- Supports both PageSpec-based and limit-based pagination modes\n- Automatically calculates total pages based on record count and page size\n\n**Constraint:** Page numbers start from 1, page size limited to prevent performance issues\n",
"modelRef": "#/components/schemas/focus.analytics.PageMetadata.out",
"customType": "focus.analytics.PageMetadata.out",
"schema": [
{
"name": "pageNumber",
"kind": "optional",
"type": "integer",
"description": "Current page number starting from 1 for one-based pagination navigation through\nanalytics query results and user-friendly page display\n",
"example": 0
},
{
"name": "pageSize",
"kind": "optional",
"type": "integer",
"description": "Number of records per page for pagination control with maximum limit\nenforced for performance optimization in large result sets\n",
"example": 0
},
{
"name": "totalPages",
"kind": "optional",
"type": "integer",
"description": "Total number of pages available based on record count and page size\ncalculation for complete pagination navigation context\n",
"example": 0
},
{
"name": "totalRecords",
"kind": "optional",
"type": "integer",
"description": "Total number of records in complete result set before pagination for\ndisplaying full dataset size information to users\n",
"example": 0
}
]
},
{
"name": "usageItems",
"kind": "optional",
"type": "array",
"description": "",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "analytics",
"kind": "optional",
"type": "array",
"description": "Enhanced time series analytics data similar to AnalyticsTimeSeries with additional detail features.\n\n**Key differences:**\n- Values include percentage change calculations via DetailedAnalyticsValues\n- Time series has no gaps (includes zeroes for missing time slots)\n- Designed for detailed analysis and visualization requirements\n",
"modelRef": "#/components/schemas/focus.analytics.DetailedAnalyticsTimeSeries.out",
"customType": "focus.analytics.DetailedAnalyticsTimeSeries.out[]",
"schema": [
{
"name": "group",
"kind": "optional",
"type": "object",
"description": "Dimensional grouping key containing predefined system dimensions and custom user dimensions for analytics aggregation",
"modelRef": "#/components/schemas/focus.analytics.AnalyticsGroupKey.out",
"customType": "focus.analytics.AnalyticsGroupKey.out",
"schema": [
{
"name": "amberfloDimensions",
"kind": "optional",
"type": "map",
"description": "Predefined field dimensions including FOCUS report columns and Amberflo managed fields like businessUnitId. Key-value pairs for standard dimensions.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "dimensions",
"kind": "optional",
"type": "map",
"description": "Ad-hoc field dimensions including meter dimensions and FOCUS report Tags. Key-value pairs for custom dimensions and user-defined groupings.",
"example": "",
"customType": "map",
"schema": []
}
]
},
{
"name": "groupValues",
"kind": "optional",
"type": "array",
"description": "Aggregated metric values for this group across the entire time range query period",
"example": "",
"itemType": "number",
"customType": "number[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "values",
"kind": "optional",
"type": "array",
"description": "Detailed time series data points with no gaps in time sequence and percentage change calculations.\n\n**Important note:** Unlike basic analytics, this includes zeroes for time slots with no data.\n",
"modelRef": "#/components/schemas/focus.analytics.DetailedAnalyticsValues.out",
"customType": "focus.analytics.DetailedAnalyticsValues.out[]",
"schema": [
{
"name": "timeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp in seconds for this data point representing the start time of the time bucket",
"example": 0
},
{
"name": "values",
"kind": "optional",
"type": "array",
"description": "Array of numeric metric values for this time point corresponding to requested usage items in order",
"example": "",
"itemType": "number",
"customType": "number[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "percentageChange",
"kind": "optional",
"type": "array",
"description": "Percentage difference from the previous time period for each metric value in the same array order.\n\n**Special cases for zero values:**\n- 0 to +X: +100%\n- 0 to -X: -100% \n- +X to 0: -100%\n- 0 to 0: 0%\n",
"example": "",
"itemType": "number",
"customType": "number[]",
"itemExample": "",
"itemDefault": ""
}
]
},
{
"name": "forecastValues",
"kind": "optional",
"type": "array",
"description": "Predicted future time series data points generated by forecasting algorithms for trend analysis",
"modelRef": "#/components/schemas/focus.analytics.AnalyticsValues.out",
"customType": "focus.analytics.AnalyticsValues.out[]",
"schema": [
{
"name": "timeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp in seconds for this data point. Represents the start time of the time bucket for aggregated data.",
"example": 0
},
{
"name": "values",
"kind": "optional",
"type": "array",
"description": "Array of numeric metric values for this time point. Each position corresponds to a requested usage item in the same order.",
"example": "",
"itemType": "number",
"customType": "number[]",
"itemExample": "",
"itemDefault": ""
}
]
}
]
},
{
"name": "timeGroupsInSeconds",
"kind": "optional",
"type": "array",
"description": "",
"example": "",
"itemType": "integer",
"customType": "integer[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "query",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/business_unit.usage_cost.BusinessUnitUsageCostQuery.out",
"customType": "business_unit.usage_cost.BusinessUnitUsageCostQuery.out",
"schema": [
{
"name": "aggregation",
"kind": "required",
"type": "string",
"description": "Mathematical aggregation function for combining data values. Currently only SUM is supported for totaling numeric metrics across time periods and dimensional groupings.",
"modelRef": "#/components/schemas/focus.analytics.AggregationType.out",
"customType": "focus.analytics.AggregationType.out",
"schema": []
},
{
"name": "timeGroupingInterval",
"kind": "optional",
"type": "string",
"description": "Time granularity for data aggregation and bucketing. HOUR creates hourly buckets, DAY creates daily buckets, WEEK creates weekly buckets starting Monday, MONTH creates monthly buckets. Each defines timestamp resolution and bucket size for time-series data.",
"modelRef": "#/components/schemas/focus.analytics.AggregationInterval.out",
"customType": "focus.analytics.AggregationInterval.out",
"schema": []
},
{
"name": "timeRange",
"kind": "required",
"type": "object",
"description": "Time period for which to execute the query.",
"modelRef": "#/components/schemas/focus.analytics.TimeRange.out",
"customType": "focus.analytics.TimeRange.out",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Start time for analytics query in Unix timestamp seconds. Inclusive lower bound for time range filtering.",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "End time for analytics query in Unix timestamp seconds. Exclusive upper bound for time range filtering.",
"example": 0
}
]
},
{
"name": "filter",
"kind": "optional",
"type": "map",
"description": "",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "groupBy",
"kind": "optional",
"type": "array",
"description": "",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "page",
"kind": "optional",
"type": "object",
"description": "Pagination specification for limiting result set size. Both number and size are required to enable proper pagination through large datasets.",
"modelRef": "#/components/schemas/focus.analytics.PageSpec.out",
"customType": "focus.analytics.PageSpec.out",
"schema": [
{
"name": "number",
"kind": "required",
"type": "integer",
"description": "Page number for pagination starting from 1. Must be at least 1 for valid pagination requests.",
"example": 0
},
{
"name": "size",
"kind": "required",
"type": "integer",
"description": "Number of records per page. Must be between 1 and 1000 inclusive for performance limits.",
"example": 0
}
]
},
{
"name": "limit",
"kind": "optional",
"type": "integer",
"description": "",
"example": 0
},
{
"name": "sort",
"kind": "optional",
"type": "object",
"description": "Sort specification for ordering query results. Defines both the fields to sort by and the sort direction, enabling consistent result ordering.",
"modelRef": "#/components/schemas/focus.analytics.SortSpec.out",
"customType": "focus.analytics.SortSpec.out",
"schema": [
{
"name": "isAscending",
"kind": "optional",
"type": "boolean",
"description": "Sort direction flag where true indicates ascending order and false indicates descending order. Defaults to false for descending.",
"example": ""
},
{
"name": "sortBy",
"kind": "required",
"type": "array",
"description": "Array of field names to sort by in priority order. Must contain at least one field and cannot have duplicates.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
}
]
},
{
"name": "usageItems",
"kind": "required",
"type": "array",
"description": "Which metrics to include in the result.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "summaryOnly",
"kind": "optional",
"type": "boolean",
"description": "Set to false to only compute the group totals and omit the values time series.",
"example": ""
},
{
"name": "forecast",
"kind": "optional",
"type": "object",
"description": "Forecast future usage. Currently, it uses a linear model.",
"modelRef": "#/components/schemas/focus.analytics.ForecastOptions.out",
"customType": "focus.analytics.ForecastOptions.out",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp for forecast period start using linear regression model on historical data.\n\n**Important note:** Defaults to query end time to avoid training on partial current period data.\n",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "required",
"type": "integer",
"description": "Unix timestamp for forecast period end defining the prediction time range boundary.\n\n**Constraint:** Must be less than one year from current time for realistic forecasting accuracy.\n",
"example": 0
}
]
},
{
"name": "subTotalBy",
"kind": "optional",
"type": "string",
"description": "",
"example": ""
}
]
},
{
"name": "totals",
"kind": "optional",
"type": "array",
"description": "",
"example": "",
"itemType": "number",
"customType": "number[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "subTotals",
"kind": "optional",
"type": "map",
"description": "",
"example": "",
"customType": "map",
"schema": []
}
],
"modelRef": "#/components/schemas/business_unit.usage_cost.DetailedBusinessUnitUsageCostQueryResult.out",
"isExpanded": true
}
]
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "Md6XjPen7xR5JIcdvnbGx",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/business-unit/usage-cost/query \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"aggregation\": \"\",\n \"timeRange\": {},\n \"page\": {\n \"number\": 0,\n \"size\": 0\n },\n \"sort\": {\n \"sortBy\": []\n },\n \"usageItems\": [],\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n }'"
},
{
"id": "svxI59xlRI7oJv0S2jk06",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"aggregation\": \"\",\n \"timeRange\": {},\n \"page\": {\n \"number\": 0,\n \"size\": 0\n },\n \"sort\": {\n \"sortBy\": []\n },\n \"usageItems\": [],\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/business-unit/usage-cost/query\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "ULSE4Y4nBM5PnCIxyNc0T",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/business-unit/usage-cost/query\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"aggregation\": \"\",\n \"timeRange\": {},\n \"page\": {\n \"number\": 0,\n \"size\": 0\n },\n \"sort\": {\n \"sortBy\": []\n },\n \"usageItems\": [],\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "fbTHQF6YPUK2PhwuSGBt4",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/business-unit/usage-cost/query\"\n\npayload = json.dumps({\n \"aggregation\": \"\",\n \"timeRange\": {},\n \"page\": {\n \"number\": 0,\n \"size\": 0\n },\n \"sort\": {\n \"sortBy\": []\n },\n \"usageItems\": [],\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "Md6XjPen7xR5JIcdvnbGx"
},
"results": {
"languages": [
{
"id": "response-0-200",
"language": "200",
"code": "// Successful request\n{\n \"pageMetadata\": {\n \"pageNumber\": \"\",\n \"pageSize\": \"\",\n \"totalPages\": \"\",\n \"totalRecords\": \"\"\n },\n \"usageItems\": [\n \"\"\n ],\n \"analytics\": [\n {\n \"group\": {\n \"amberfloDimensions\": \"\",\n \"dimensions\": \"\"\n },\n \"groupValues\": [\n 0\n ],\n \"values\": [\n {\n \"timeInSeconds\": \"\",\n \"values\": [\n 0\n ],\n \"percentageChange\": [\n 0\n ]\n }\n ],\n \"forecastValues\": [\n {\n \"timeInSeconds\": \"\",\n \"values\": [\n 0\n ]\n }\n ]\n }\n ],\n \"timeGroupsInSeconds\": [\n 0\n ],\n \"query\": {\n \"aggregation\": \"\",\n \"timeGroupingInterval\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n },\n \"filter\": \"\",\n \"groupBy\": [\n \"\"\n ],\n \"page\": {\n \"number\": \"\",\n \"size\": \"\"\n },\n \"limit\": \"\",\n \"sort\": {\n \"isAscending\": false,\n \"sortBy\": [\n \"\"\n ]\n },\n \"usageItems\": [\n \"\"\n ],\n \"summaryOnly\": false,\n \"forecast\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n },\n \"subTotalBy\": \"\"\n },\n \"totals\": [\n 0\n ],\n \"subTotals\": \"\"\n}"
}
],
"selectedLanguageId": "response-0-200"
}
},
"children": [
{
"text": "",
"id": "oTOoeF8IdBub5YzfUHOkp"
}
]
}