Execute optimized cost query for dashboards

1 min

POST

https://app.amberflo.io/business-unit/usage-cost/query/sparse

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.

Body Parameters

bodybusiness_unit.usage_cost.BusinessUnitUsageCostQuery.in
- aggregationfocus.analytics.AggregationType.inrequired
  Description
  Mathematical aggregation function for combining data values. Currently only SUM is supported for totaling numeric metrics across time periods and dimensional groupings.
- timeGroupingIntervalfocus.analytics.AggregationInterval.in
  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.
- timeRangefocus.analytics.TimeRange.inrequired
  Description
  Time period for which to execute the query.
  - startTimeInSecondsinteger<int64>
    Description
    Start time for analytics query in Unix timestamp seconds. Inclusive lower bound for time range filtering.
  - endTimeInSecondsinteger<int64>
    Description
    End time for analytics query in Unix timestamp seconds. Exclusive upper bound for time range filtering.
- filtermap<string, string[]>
- groupBystring[]
- pagefocus.analytics.PageSpec.in
  Description
  Pagination specification for limiting result set size. Both number and size are required to enable proper pagination through large datasets.
  - numberinteger<int32>required
    Description
    Page number for pagination starting from 1. Must be at least 1 for valid pagination requests.
  - sizeinteger<int32>required
    Description
    Number of records per page. Must be between 1 and 1000 inclusive for performance limits.
- limitinteger<int32>
- sortfocus.analytics.SortSpec.in
  Description
  Sort specification for ordering query results. Defines both the fields to sort by and the sort direction, enabling consistent result ordering.
  - isAscendingboolean
    Description
    Sort direction flag where true indicates ascending order and false indicates descending order. Defaults to false for descending.
  - sortBystring[]required
    Description
    Array of field names to sort by in priority order. Must contain at least one field and cannot have duplicates.
- usageItemsstring[]required
  Description
  Which metrics to include in the result.
- summaryOnlyboolean
  Description
  Set to false to only compute the group totals and omit the values time series.
- forecastfocus.analytics.ForecastOptions.in
  Description
  Forecast future usage. Currently, it uses a linear model.
  - startTimeInSecondsinteger<int64>
    Description
    Unix timestamp for forecast period start using linear regression model on historical data. **Important note:** Defaults to query end time to avoid training on partial current period data.
  - endTimeInSecondsinteger<int64>required
    Description
    Unix timestamp for forecast period end defining the prediction time range boundary. **Constraint:** Must be less than one year from current time for realistic forecasting accuracy.
- subTotalBystring

Responses

200Successful request

business_unit.usage_cost.BusinessUnitUsageCostQueryResult.out
- pageMetadatafocus.analytics.PageMetadata.out
  Description
  **Analytics pagination metadata for result navigation** **Important note:** Provides pagination context for analytics query results with page navigation details **Technical details:** - Supports both PageSpec-based and limit-based pagination modes - Automatically calculates total pages based on record count and page size **Constraint:** Page numbers start from 1, page size limited to prevent performance issues
  - pageNumberinteger<int32>
    Description
    Current page number starting from 1 for one-based pagination navigation through analytics query results and user-friendly page display
  - pageSizeinteger<int32>
    Description
    Number of records per page for pagination control with maximum limit enforced for performance optimization in large result sets
  - totalPagesinteger<int32>
    Description
    Total number of pages available based on record count and page size calculation for complete pagination navigation context
  - totalRecordsinteger<int32>
    Description
    Total number of records in complete result set before pagination for displaying full dataset size information to users
- usageItemsstring[]
- analyticsfocus.analytics.AnalyticsTimeSeries.out[]
  Description
  Time series analytics data for a single dimensional group containing historical values and optional forecasting predictions
  - groupfocus.analytics.AnalyticsGroupKey.out
    Description
    Dimensional grouping key containing predefined system dimensions and custom user dimensions for analytics aggregation
    - amberfloDimensionsmap<string, string>
      Description
      Predefined field dimensions including FOCUS report columns and Amberflo managed fields like businessUnitId. Key-value pairs for standard dimensions.
    - dimensionsmap<string, string>
      Description
      Ad-hoc field dimensions including meter dimensions and FOCUS report Tags. Key-value pairs for custom dimensions and user-defined groupings.
  - groupValuesnumber[]
    Description
    Aggregated metric values for this group across the entire time range query period
  - valuesfocus.analytics.AnalyticsValues.out[]
    Description
    Historical time series data points containing timestamps and corresponding metric values for this group
    - timeInSecondsinteger<int64>
      Description
      Unix timestamp in seconds for this data point. Represents the start time of the time bucket for aggregated data.
    - valuesnumber[]
      Description
      Array of numeric metric values for this time point. Each position corresponds to a requested usage item in the same order.
  - forecastValuesfocus.analytics.AnalyticsValues.out[]
    Description
    Predicted future time series data points generated by forecasting algorithms for trend analysis
    - timeInSecondsinteger<int64>
      Description
      Unix timestamp in seconds for this data point. Represents the start time of the time bucket for aggregated data.
    - valuesnumber[]
      Description
      Array of numeric metric values for this time point. Each position corresponds to a requested usage item in the same order.
- querybusiness_unit.usage_cost.BusinessUnitUsageCostQuery.out
  - aggregationfocus.analytics.AggregationType.outrequired
    Description
    Mathematical aggregation function for combining data values. Currently only SUM is supported for totaling numeric metrics across time periods and dimensional groupings.
  - timeGroupingIntervalfocus.analytics.AggregationInterval.out
    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.
  - timeRangefocus.analytics.TimeRange.outrequired
    Description
    Time period for which to execute the query.
    - startTimeInSecondsinteger<int64>
      Description
      Start time for analytics query in Unix timestamp seconds. Inclusive lower bound for time range filtering.
    - endTimeInSecondsinteger<int64>
      Description
      End time for analytics query in Unix timestamp seconds. Exclusive upper bound for time range filtering.
  - filtermap<string, string[]>
  - groupBystring[]
  - pagefocus.analytics.PageSpec.out
    Description
    Pagination specification for limiting result set size. Both number and size are required to enable proper pagination through large datasets.
    - numberinteger<int32>required
      Description
      Page number for pagination starting from 1. Must be at least 1 for valid pagination requests.
    - sizeinteger<int32>required
      Description
      Number of records per page. Must be between 1 and 1000 inclusive for performance limits.
  - limitinteger<int32>
  - sortfocus.analytics.SortSpec.out
    Description
    Sort specification for ordering query results. Defines both the fields to sort by and the sort direction, enabling consistent result ordering.
    - isAscendingboolean
      Description
      Sort direction flag where true indicates ascending order and false indicates descending order. Defaults to false for descending.
    - sortBystring[]required
      Description
      Array of field names to sort by in priority order. Must contain at least one field and cannot have duplicates.
  - usageItemsstring[]required
    Description
    Which metrics to include in the result.
  - summaryOnlyboolean
    Description
    Set to false to only compute the group totals and omit the values time series.
  - forecastfocus.analytics.ForecastOptions.out
    Description
    Forecast future usage. Currently, it uses a linear model.
    - startTimeInSecondsinteger<int64>
      Description
      Unix timestamp for forecast period start using linear regression model on historical data. **Important note:** Defaults to query end time to avoid training on partial current period data.
    - endTimeInSecondsinteger<int64>required
      Description
      Unix timestamp for forecast period end defining the prediction time range boundary. **Constraint:** Must be less than one year from current time for realistic forecasting accuracy.
  - subTotalBystring
- totalsnumber[]
- subTotalsmap<string, number[]>

curl

curl --request POST \
     --url https://app.amberflo.io/business-unit/usage-cost/query/sparse \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "aggregation": "",
     "timeRange": {},
     "page": {
     "number": 0,
     "size": 0
     },
     "sort": {
     "sortBy": []
     },
     "usageItems": [],
     "forecast": {
     "endTimeInSeconds": 0
     }
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "aggregation": "",
   "timeRange": {},
   "page": {
      "number": 0,
      "size": 0
   },
   "sort": {
      "sortBy": []
   },
   "usageItems": [],
   "forecast": {
      "endTimeInSeconds": 0
   }
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://app.amberflo.io/business-unit/usage-cost/query/sparse", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://app.amberflo.io/business-unit/usage-cost/query/sparse")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "aggregation": "",
   "timeRange": {},
   "page": {
      "number": 0,
      "size": 0
   },
   "sort": {
      "sortBy": []
   },
   "usageItems": [],
   "forecast": {
      "endTimeInSeconds": 0
   }
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://app.amberflo.io/business-unit/usage-cost/query/sparse"

payload = json.dumps({
   "aggregation": "",
   "timeRange": {},
   "page": {
      "number": 0,
      "size": 0
   },
   "sort": {
      "sortBy": []
   },
   "usageItems": [],
   "forecast": {
      "endTimeInSeconds": 0
   }
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Successful request
{
  "pageMetadata": {
    "pageNumber": "",
    "pageSize": "",
    "totalPages": "",
    "totalRecords": ""
  },
  "usageItems": [
    ""
  ],
  "analytics": [
    {
      "group": {
        "amberfloDimensions": "",
        "dimensions": ""
      },
      "groupValues": [
        0
      ],
      "values": [
        {
          "timeInSeconds": "",
          "values": [
            0
          ]
        }
      ],
      "forecastValues": [
        {
          "timeInSeconds": "",
          "values": [
            0
          ]
        }
      ]
    }
  ],
  "query": {
    "aggregation": "",
    "timeGroupingInterval": "",
    "timeRange": {
      "startTimeInSeconds": "",
      "endTimeInSeconds": ""
    },
    "filter": "",
    "groupBy": [
      ""
    ],
    "page": {
      "number": "",
      "size": ""
    },
    "limit": "",
    "sort": {
      "isAscending": false,
      "sortBy": [
        ""
      ]
    },
    "usageItems": [
      ""
    ],
    "summaryOnly": false,
    "forecast": {
      "startTimeInSeconds": "",
      "endTimeInSeconds": ""
    },
    "subTotalBy": ""
  },
  "totals": [
    0
  ],
  "subTotals": ""
}