Query the usage data

1 min

POST

https://app.amberflo.io/usage

This API is a generic statistical query tool which can allow you to fetch the usage or usage-rate (scale of usage) over time.

In order to facilitate using the response for plotting charts, this endpoint will fill the gaps in the time series when no usage happened. If this is not needed, consider using the sparse usage endpoint.

Body Parameters

bodyusage.MeterAggregationMetadata.in
- meterApiNamestringrequired
  Description
  `meterApiName` as defined in [Meter API](ref:post_meters).
- aggregationusage.AggregationType.in
  Description
  Aggregation function. If not specified, the default is obtained from the associated meter definition.
- timeRangecommon.TimeRange.inrequired
  Description
  Time period for which to compute the usage.
  - 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 for the usage query. Each entry is a dimension and a list of values to filter for.", 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
  Group the usage data by these dimensions. 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
  - limitinteger<int32>required
  - isAscendingboolean
- timeGroupingIntervalcom.amberflo.service.common.aggregation.AggregationInterval.in
  Description
  A usage query returns a time series of statistics. This field specifies the granularity of the time buckets in this series. 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.
- valuesTimeGroupingIntervalcom.amberflo.service.common.aggregation.AggregationInterval.in
- rescaleFunctioncom.amberflo.service.common.aggregation.RescaleFunction.in
  - functioncom.amberflo.service.common.aggregation.RescaleFunctionType.in
  - coefficientnumber

Responses

200Successful request

usage.DetailedMeterAggregation.out
- metadatausage.MeterAggregationMetadata.out
  - accountstring
  - meterApiNamestringrequired
    Description
    `meterApiName` as defined in [Meter API](ref:post_meters).
  - aggregationusage.AggregationType.out
    Description
    Aggregation function. If not specified, the default is obtained from the associated meter definition.
  - timeRangecommon.TimeRange.outrequired
    Description
    Time period for which to compute the usage.
    - 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 for the usage query. Each entry is a dimension and a list of values to filter for.", 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
    Group the usage data by these dimensions. 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
    - limitinteger<int32>required
    - isAscendingboolean
  - timeGroupingIntervalcom.amberflo.service.common.aggregation.AggregationInterval.out
    Description
    A usage query returns a time series of statistics. This field specifies the granularity of the time buckets in this series. 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.
  - valuesTimeGroupingIntervalcom.amberflo.service.common.aggregation.AggregationInterval.out
  - rescaleFunctioncom.amberflo.service.common.aggregation.RescaleFunction.out
    - functioncom.amberflo.service.common.aggregation.RescaleFunctionType.out
    - coefficientnumber
- secondsSinceEpochIntervalsinteger[]
- clientMetersusage.DetailedMeterAggregation.DetailedMeterAggregationGroup.out[]
  - groupusage.MeterAggregation.GroupInfo.out
    - groupInfomap<string, string>
  - groupValuenumber
  - valuesusage.DetailedMeterAggregation.DetailedAggregationValue.out[]
    - valuenumber
    - secondsSinceEpochUtcinteger<int64>
    - percentageFromPreviousnumber

curl

curl --request POST \
     --url https://app.amberflo.io/usage \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "meterApiName": "",
     "timeRange": {
     "startTimeInSeconds": 0
     },
     "take": {
     "limit": 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
   }
});

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

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

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
   }
})

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

python

import requests
import json

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

payload = json.dumps({
   "meterApiName": "",
   "timeRange": {
      "startTimeInSeconds": 0
   },
   "take": {
      "limit": 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
    }
  },
  "secondsSinceEpochIntervals": [
    0
  ],
  "clientMeters": [
    {
      "group": {
        "groupInfo": ""
      },
      "groupValue": 0,
      "values": [
        {
          "value": 0,
          "secondsSinceEpochUtc": "",
          "percentageFromPrevious": 0
        }
      ]
    }
  ]
}

This API is a generic statistical query tool which can allow you to fetch the usage or usage-rate (scale of usage) over time.