---
title: Execute optimized cost query for dashboards
slug: reference/execute-optimized-cost-query-for-dashboards
docTags:
createdAt: 2025-07-03T16:20:35.017Z
---
{
"id": "sfjz_EORfvPETVdrD1Yc0",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/business-unit/usage-cost/query/sparse",
"servers": [
{
"url": "https://app.amberflo.io/business-unit/usage-cost/query/sparse"
}
],
"name": "Execute optimized cost query for dashboards",
"description": "Execute optimized analytics queries for business unit usage and costs with sparse result format for improved performance on large datasets. Returns summarized cost data with reduced granularity, ideal for dashboard overviews, high-level reporting, and real-time cost monitoring where detailed breakdowns are not required.
",
"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.BusinessUnitUsageCostQueryResult.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": "Time series analytics data for a single dimensional group containing historical values and optional forecasting predictions",
"modelRef": "#/components/schemas/focus.analytics.AnalyticsTimeSeries.out",
"customType": "focus.analytics.AnalyticsTimeSeries.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": "Historical time series data points containing timestamps and corresponding metric values for this group",
"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": "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": "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.BusinessUnitUsageCostQueryResult.out",
"isExpanded": true
}
]
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "wMCTAo2oobnsZdQy0a_Ci",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/business-unit/usage-cost/query/sparse \\\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": "Ff0OGvFQj1z5DB-pcDsJ0",
"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/sparse\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "qjrVT7veH7FNoyjJZhdpw",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/business-unit/usage-cost/query/sparse\")\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": "obesgIOlPG3GRNyfaZlkx",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/business-unit/usage-cost/query/sparse\"\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": "wMCTAo2oobnsZdQy0a_Ci"
},
"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 }\n ],\n \"forecastValues\": [\n {\n \"timeInSeconds\": \"\",\n \"values\": [\n 0\n ]\n }\n ]\n }\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": "xUzDpaOhq2BxjwKlt7Wr9"
}
]
}