Query the usage data (sparse)

1 min

POST

https://app.amberflo.io/usage/sparse/batch

Queries usage data for multiple meters in batch mode, returning only periods with actual usage events. Takes an array of usage queries and returns sparse results without time series gap filling.

Common use cases:

Bulk export of raw usage data across multiple meters
Retrieve actual usage patterns for external analytics systems
Compare sparse usage events between different meters efficiently
Generate reports that focus only on active usage periods

Each query supports the same filtering and grouping options as individual sparse queries, returning only time periods where usage events were recorded.

Important: Returns sparse data without time series interpolation. For continuous charting, use the standard batch usage query instead.

Body Parameters

bodyusage.MeterAggregationMetadata.in[]
Description
Query parameters for retrieving aggregated meter usage data with filtering and grouping options
- meterApiNamestringrequired
  Description
  Technical identifier of the meter to query usage data from as defined in the Meter API.
- aggregationusage.AggregationType.in
  Description
  Mathematical function for aggregating usage data. If not specified, the default is obtained from the associated meter definition.
- timeRangecommon.TimeRange.inrequired
  Description
  Time period boundaries for computing usage statistics and aggregations.
  - startTimeInSecondsinteger<int64>required
    Description
    Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).
  - endTimeInSecondsinteger<int64>
    Description
    End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to "now".
- filtermap<string, string[]>
  Description
  WHERE clause conditions for filtering usage query results by dimension values. Valid filters are: - `customerId` - Any dimension defined in for the meter, see the [Meter API](ref:post_meters). - `tags:<tagId>` Different filters are combined using logical `AND` operator while different filter values for a given key are combined using logic `OR` operator. Tags can be specified in filters using the prefix `tags:`. For example, 1. `tags:stage = [prod, dev]` will filter usage by all customer having tag `stage.prod` **or** `stage.dev` 2. `tags:stage = [prod], tags:region = [us-west]` will filter usage by customers having tags `stage.prod` **and** `region.us-west-2`.
- groupBystring[]
  Description
  Dimensions for grouping usage data into separate aggregation buckets. If unspecified or empty, data will be aggregated for the meter as a whole. Valid values are: - `customerId` - `customerName` - Any dimension defined in for the meter, see the [Meter API](ref:post_meters).
- takeusage.MeterAggregationMetadata.Take.in
  Description
  Limits the number of results returned and specifies sorting order for result selection.
  - limitinteger<int32>required
    Description
    Maximum number of results to return from the query. Must be greater than 0.
  - isAscendingboolean
    Description
    Whether to sort results in ascending order (true) or descending order (false) when selecting the limited results.
- timeGroupingIntervalcommon.aggregation.AggregationInterval.in
  Description
  Time granularity for bucketing usage statistics in the returned time series data. Notice that for aggregation types: `MIN`, `MAX`, `AVG` this field has a more delicate meaning. For example, for `AVG` if this field value is an `HOUR`, then you get the hourly average usage value for each group and a breakdown of each hour usage. On the other hand if this field is a `DAY` then you get the average of the total daily usage, with a breakdown of the total usage per day.
- valuesTimeGroupingIntervalcommon.aggregation.AggregationInterval.in
  Description
  Internal time interval for individual aggregation values, allowing different granularity than timeGroupingInterval.
- rescaleFunctioncommon.aggregation.RescaleFunction.in
  Description
  Mathematical transformation applied to scale the reported usage values before returning results.
  - functioncommon.aggregation.RescaleFunctionType.in
    Description
    Mathematical operation type to apply for scaling the usage values
  - coefficientnumber
    Description
    Numerical multiplier value used in the scaling transformation calculation
- forecastusage.ForecastOptions.in
  Description
  Configuration for predicting future usage patterns using linear modeling algorithms. Note that forecasting happens after rescaling.
  - startTimeInSecondsinteger<int64>
    Description
    Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to the end time of the historical usage.
  - endTimeInSecondsinteger<int64>required
    Description
    End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).

Responses

200Successful request

usage.MeterAggregation.out[]
Description
Aggregated meter data including metadata and grouped client measurements for specific meter analysis
- metadatausage.MeterAggregationMetadata.out
  Description
  Configuration metadata including aggregation intervals, grouping functions, and filtering rules
  - accountstring
    Description
    Unique identifier of the account that owns the meter being queried.
  - meterApiNamestringrequired
    Description
    Technical identifier of the meter to query usage data from as defined in the Meter API.
  - aggregationusage.AggregationType.out
    Description
    Mathematical function for aggregating usage data. If not specified, the default is obtained from the associated meter definition.
  - timeRangecommon.TimeRange.outrequired
    Description
    Time period boundaries for computing usage statistics and aggregations.
    - startTimeInSecondsinteger<int64>required
      Description
      Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).
    - endTimeInSecondsinteger<int64>
      Description
      End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to "now".
  - filtermap<string, string[]>
    Description
    WHERE clause conditions for filtering usage query results by dimension values. Valid filters are: - `customerId` - Any dimension defined in for the meter, see the [Meter API](ref:post_meters). - `tags:<tagId>` Different filters are combined using logical `AND` operator while different filter values for a given key are combined using logic `OR` operator. Tags can be specified in filters using the prefix `tags:`. For example, 1. `tags:stage = [prod, dev]` will filter usage by all customer having tag `stage.prod` **or** `stage.dev` 2. `tags:stage = [prod], tags:region = [us-west]` will filter usage by customers having tags `stage.prod` **and** `region.us-west-2`.
  - groupBystring[]
    Description
    Dimensions for grouping usage data into separate aggregation buckets. If unspecified or empty, data will be aggregated for the meter as a whole. Valid values are: - `customerId` - `customerName` - Any dimension defined in for the meter, see the [Meter API](ref:post_meters).
  - takeusage.MeterAggregationMetadata.Take.out
    Description
    Limits the number of results returned and specifies sorting order for result selection.
    - limitinteger<int32>required
      Description
      Maximum number of results to return from the query. Must be greater than 0.
    - isAscendingboolean
      Description
      Whether to sort results in ascending order (true) or descending order (false) when selecting the limited results.
  - timeGroupingIntervalcommon.aggregation.AggregationInterval.out
    Description
    Time granularity for bucketing usage statistics in the returned time series data. Notice that for aggregation types: `MIN`, `MAX`, `AVG` this field has a more delicate meaning. For example, for `AVG` if this field value is an `HOUR`, then you get the hourly average usage value for each group and a breakdown of each hour usage. On the other hand if this field is a `DAY` then you get the average of the total daily usage, with a breakdown of the total usage per day.
  - valuesTimeGroupingIntervalcommon.aggregation.AggregationInterval.out
    Description
    Internal time interval for individual aggregation values, allowing different granularity than timeGroupingInterval.
  - rescaleFunctioncommon.aggregation.RescaleFunction.out
    Description
    Mathematical transformation applied to scale the reported usage values before returning results.
    - functioncommon.aggregation.RescaleFunctionType.out
      Description
      Mathematical operation type to apply for scaling the usage values
    - coefficientnumber
      Description
      Numerical multiplier value used in the scaling transformation calculation
  - forecastusage.ForecastOptions.out
    Description
    Configuration for predicting future usage patterns using linear modeling algorithms. Note that forecasting happens after rescaling.
    - startTimeInSecondsinteger<int64>
      Description
      Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to the end time of the historical usage.
    - endTimeInSecondsinteger<int64>required
      Description
      End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).
- clientMetersusage.MeterAggregation.MeterAggregationGroup.out[]
  Description
  Collection of meter aggregation groups containing computed values organized by customer dimensions
  - groupusage.MeterAggregation.GroupInfo.out
    Description
    Dimension information defining how this aggregation group is organized by customer attributes
    - groupInfomap<string, string>
      Description
      Map of dimension names to values used for grouping meter aggregations by customer attributes
  - groupValuenumber
    Description
    Total aggregated value for this group across all time periods in the query range
  - valuesusage.MeterAggregation.AggregationValue.out[]
    Description
    Time-series of aggregated values showing usage progression over time for this group
    - valuenumber
      Description
      Computed aggregated measurement value for the meter at the specified time point
    - secondsSinceEpochUtcinteger<int64>
      Description
      UTC timestamp in seconds since epoch when this aggregated value was recorded or computed
  - forecastValuesusage.MeterAggregation.AggregationValue.out[]
    Description
    Predicted future aggregated values based on historical patterns for this group
    - valuenumber
      Description
      Computed aggregated measurement value for the meter at the specified time point
    - secondsSinceEpochUtcinteger<int64>
      Description
      UTC timestamp in seconds since epoch when this aggregated value was recorded or computed

curl

curl --request POST \
     --url https://app.amberflo.io/usage/sparse/batch \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '[
     {
     "meterApiName": "",
     "timeRange": {
     "startTimeInSeconds": 0
     },
     "take": {
     "limit": 0
     },
     "forecast": {
     "endTimeInSeconds": 0
     }
     }
     ]'

javascript

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

var raw = JSON.stringify([
   {
      "meterApiName": "",
      "timeRange": {
         "startTimeInSeconds": 0
      },
      "take": {
         "limit": 0
      },
      "forecast": {
         "endTimeInSeconds": 0
      }
   }
]);

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

fetch("https://app.amberflo.io/usage/sparse/batch", 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/usage/sparse/batch")

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([
   {
      "meterApiName": "",
      "timeRange": {
         "startTimeInSeconds": 0
      },
      "take": {
         "limit": 0
      },
      "forecast": {
         "endTimeInSeconds": 0
      }
   }
])

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

python

import requests
import json

url = "https://app.amberflo.io/usage/sparse/batch"

payload = json.dumps([
   {
      "meterApiName": "",
      "timeRange": {
         "startTimeInSeconds": 0
      },
      "take": {
         "limit": 0
      },
      "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
[
  {
    "metadata": {
      "account": "",
      "meterApiName": "",
      "aggregation": "",
      "timeRange": {
        "startTimeInSeconds": "",
        "endTimeInSeconds": ""
      },
      "filter": "",
      "groupBy": [
        ""
      ],
      "take": {
        "limit": "",
        "isAscending": false
      },
      "timeGroupingInterval": "",
      "valuesTimeGroupingInterval": "",
      "rescaleFunction": {
        "function": "",
        "coefficient": 0
      },
      "forecast": {
        "startTimeInSeconds": "",
        "endTimeInSeconds": ""
      }
    },
    "clientMeters": [
      {
        "group": {
          "groupInfo": ""
        },
        "groupValue": 0,
        "values": [
          {
            "value": 0,
            "secondsSinceEpochUtc": ""
          }
        ],
        "forecastValues": [
          {
            "value": 0,
            "secondsSinceEpochUtc": ""
          }
        ]
      }
    ]
  }
]