--- title: Query the usage data slug: reference/query-the-usage-data docTags: createdAt: 2025-01-21T18:39:14.860Z --- { "id": "t1pzrz0ZknK9G74d3Xgn1", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://app.amberflo.io/usage", "servers": [ { "url": "https://app.amberflo.io/usage" } ], "name": "Query the usage data", "description": "

Queries aggregated usage data for a specific meter over a time period.

\n

Request parameters:

\n\n

The response includes aggregated values and automatically fills gaps in the time series with zero values, making it suitable for generating continuous charts and reports.

\n

Query performance depends on time range size and grouping complexity. Use shorter time ranges or coarser intervals for better performance.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "object", "description": "Query parameters for retrieving aggregated meter usage data with filtering and grouping options", "customType": "usage.MeterAggregationMetadata.in", "schema": [ { "name": "meterApiName", "kind": "required", "type": "string", "description": "Technical identifier of the meter to query usage data from as defined in the Meter API.", "example": "" }, { "name": "aggregation", "kind": "optional", "type": "string", "description": "Mathematical function for aggregating usage data. If not specified, the default is obtained from the associated meter definition.", "modelRef": "#/components/schemas/usage.AggregationType.in", "customType": "usage.AggregationType.in", "schema": [] }, { "name": "timeRange", "kind": "required", "type": "object", "description": "Time period boundaries for computing usage statistics and aggregations.", "modelRef": "#/components/schemas/common.TimeRange.in", "customType": "common.TimeRange.in", "schema": [ { "name": "startTimeInSeconds", "kind": "required", "type": "integer", "description": "Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).", "example": 0 }, { "name": "endTimeInSeconds", "kind": "optional", "type": "integer", "description": "End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to \"now\".", "example": 0 } ] }, { "name": "filter", "kind": "optional", "type": "map", "description": "WHERE clause conditions for filtering usage query results by dimension values.\n\nValid filters are:\n- `customerId`\n- Any dimension defined in for the meter, see the [Meter API](ref:post_meters).\n- `tags:`\n\nDifferent filters are combined using logical `AND` operator while different filter values for a given key are combined using logic `OR` operator.\n\nTags can be specified in filters using the prefix `tags:`. For example,\n\n1. `tags:stage = [prod, dev]` will filter usage by all customer having tag `stage.prod` **or** `stage.dev`\n2. `tags:stage = [prod], tags:region = [us-west]` will filter usage by customers having tags `stage.prod` **and** `region.us-west-2`.", "example": "", "customType": "map", "schema": [] }, { "name": "groupBy", "kind": "optional", "type": "array", "description": "Dimensions for grouping usage data into separate aggregation buckets. If unspecified or empty, data will be aggregated for the meter as a whole.\n\nValid values are:\n- `customerId`\n- `customerName`\n- Any dimension defined in for the meter, see the [Meter API](ref:post_meters).\n", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "take", "kind": "optional", "type": "object", "description": "Limits the number of results returned and specifies sorting order for result selection.", "modelRef": "#/components/schemas/usage.MeterAggregationMetadata.Take.in", "customType": "usage.MeterAggregationMetadata.Take.in", "schema": [ { "name": "limit", "kind": "required", "type": "integer", "description": "Maximum number of results to return from the query. Must be greater than 0.", "example": 0 }, { "name": "isAscending", "kind": "optional", "type": "boolean", "description": "Whether to sort results in ascending order (true) or descending order (false) when selecting the limited results.", "example": "" } ] }, { "name": "timeGroupingInterval", "kind": "optional", "type": "string", "description": "Time granularity for bucketing usage statistics in the returned time series data.\n\nNotice that for aggregation types: `MIN`, `MAX`, `AVG` this field has a more delicate meaning.\n\nFor 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.\n\nOn 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.\n", "modelRef": "#/components/schemas/common.aggregation.AggregationInterval.in", "customType": "common.aggregation.AggregationInterval.in", "schema": [] }, { "name": "valuesTimeGroupingInterval", "kind": "optional", "type": "string", "description": "Internal time interval for individual aggregation values, allowing different granularity than timeGroupingInterval.", "modelRef": "#/components/schemas/common.aggregation.AggregationInterval.in", "customType": "common.aggregation.AggregationInterval.in", "schema": [] }, { "name": "rescaleFunction", "kind": "optional", "type": "object", "description": "Mathematical transformation applied to scale the reported usage values before returning results.", "modelRef": "#/components/schemas/common.aggregation.RescaleFunction.in", "customType": "common.aggregation.RescaleFunction.in", "schema": [ { "name": "function", "kind": "optional", "type": "string", "description": "Mathematical operation type to apply for scaling the usage values", "modelRef": "#/components/schemas/common.aggregation.RescaleFunctionType.in", "customType": "common.aggregation.RescaleFunctionType.in", "schema": [] }, { "name": "coefficient", "kind": "optional", "type": "number", "description": "Numerical multiplier value used in the scaling transformation calculation", "example": "" } ] }, { "name": "forecast", "kind": "optional", "type": "object", "description": "Configuration for predicting future usage patterns using linear modeling algorithms.\n\nNote that forecasting happens after rescaling.\n", "modelRef": "#/components/schemas/usage.ForecastOptions.in", "customType": "usage.ForecastOptions.in", "schema": [ { "name": "startTimeInSeconds", "kind": "optional", "type": "integer", "description": "Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to the end time of the historical usage.", "example": 0 }, { "name": "endTimeInSeconds", "kind": "required", "type": "integer", "description": "End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).", "example": 0 } ] } ], "modelRef": "#/components/schemas/usage.MeterAggregationMetadata.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": "Human-friendly detailed meter aggregation with time intervals array for comprehensive usage analysis", "customType": "usage.DetailedMeterAggregation.out", "schema": [ { "name": "metadata", "kind": "optional", "type": "object", "description": "Configuration metadata including aggregation intervals, grouping functions, and filtering rules", "modelRef": "#/components/schemas/usage.MeterAggregationMetadata.out", "customType": "usage.MeterAggregationMetadata.out", "schema": [ { "name": "account", "kind": "optional", "type": "string", "description": "Unique identifier of the account that owns the meter being queried.", "example": "" }, { "name": "meterApiName", "kind": "required", "type": "string", "description": "Technical identifier of the meter to query usage data from as defined in the Meter API.", "example": "" }, { "name": "aggregation", "kind": "optional", "type": "string", "description": "Mathematical function for aggregating usage data. If not specified, the default is obtained from the associated meter definition.", "modelRef": "#/components/schemas/usage.AggregationType.out", "customType": "usage.AggregationType.out", "schema": [] }, { "name": "timeRange", "kind": "required", "type": "object", "description": "Time period boundaries for computing usage statistics and aggregations.", "modelRef": "#/components/schemas/common.TimeRange.out", "customType": "common.TimeRange.out", "schema": [ { "name": "startTimeInSeconds", "kind": "required", "type": "integer", "description": "Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).", "example": 0 }, { "name": "endTimeInSeconds", "kind": "optional", "type": "integer", "description": "End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to \"now\".", "example": 0 } ] }, { "name": "filter", "kind": "optional", "type": "map", "description": "WHERE clause conditions for filtering usage query results by dimension values.\n\nValid filters are:\n- `customerId`\n- Any dimension defined in for the meter, see the [Meter API](ref:post_meters).\n- `tags:`\n\nDifferent filters are combined using logical `AND` operator while different filter values for a given key are combined using logic `OR` operator.\n\nTags can be specified in filters using the prefix `tags:`. For example,\n\n1. `tags:stage = [prod, dev]` will filter usage by all customer having tag `stage.prod` **or** `stage.dev`\n2. `tags:stage = [prod], tags:region = [us-west]` will filter usage by customers having tags `stage.prod` **and** `region.us-west-2`.", "example": "", "customType": "map", "schema": [] }, { "name": "groupBy", "kind": "optional", "type": "array", "description": "Dimensions for grouping usage data into separate aggregation buckets. If unspecified or empty, data will be aggregated for the meter as a whole.\n\nValid values are:\n- `customerId`\n- `customerName`\n- Any dimension defined in for the meter, see the [Meter API](ref:post_meters).\n", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "take", "kind": "optional", "type": "object", "description": "Limits the number of results returned and specifies sorting order for result selection.", "modelRef": "#/components/schemas/usage.MeterAggregationMetadata.Take.out", "customType": "usage.MeterAggregationMetadata.Take.out", "schema": [ { "name": "limit", "kind": "required", "type": "integer", "description": "Maximum number of results to return from the query. Must be greater than 0.", "example": 0 }, { "name": "isAscending", "kind": "optional", "type": "boolean", "description": "Whether to sort results in ascending order (true) or descending order (false) when selecting the limited results.", "example": "" } ] }, { "name": "timeGroupingInterval", "kind": "optional", "type": "string", "description": "Time granularity for bucketing usage statistics in the returned time series data.\n\nNotice that for aggregation types: `MIN`, `MAX`, `AVG` this field has a more delicate meaning.\n\nFor 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.\n\nOn 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.\n", "modelRef": "#/components/schemas/common.aggregation.AggregationInterval.out", "customType": "common.aggregation.AggregationInterval.out", "schema": [] }, { "name": "valuesTimeGroupingInterval", "kind": "optional", "type": "string", "description": "Internal time interval for individual aggregation values, allowing different granularity than timeGroupingInterval.", "modelRef": "#/components/schemas/common.aggregation.AggregationInterval.out", "customType": "common.aggregation.AggregationInterval.out", "schema": [] }, { "name": "rescaleFunction", "kind": "optional", "type": "object", "description": "Mathematical transformation applied to scale the reported usage values before returning results.", "modelRef": "#/components/schemas/common.aggregation.RescaleFunction.out", "customType": "common.aggregation.RescaleFunction.out", "schema": [ { "name": "function", "kind": "optional", "type": "string", "description": "Mathematical operation type to apply for scaling the usage values", "modelRef": "#/components/schemas/common.aggregation.RescaleFunctionType.out", "customType": "common.aggregation.RescaleFunctionType.out", "schema": [] }, { "name": "coefficient", "kind": "optional", "type": "number", "description": "Numerical multiplier value used in the scaling transformation calculation", "example": "" } ] }, { "name": "forecast", "kind": "optional", "type": "object", "description": "Configuration for predicting future usage patterns using linear modeling algorithms.\n\nNote that forecasting happens after rescaling.\n", "modelRef": "#/components/schemas/usage.ForecastOptions.out", "customType": "usage.ForecastOptions.out", "schema": [ { "name": "startTimeInSeconds", "kind": "optional", "type": "integer", "description": "Start time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds). Defaults to the end time of the historical usage.", "example": 0 }, { "name": "endTimeInSeconds", "kind": "required", "type": "integer", "description": "End time, in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (seconds).", "example": 0 } ] } ] }, { "name": "secondsSinceEpochIntervals", "kind": "optional", "type": "array", "description": "Array of UTC timestamps in seconds representing time interval boundaries for the aggregation periods", "example": "", "itemType": "integer", "customType": "integer[]", "itemExample": "", "itemDefault": "" }, { "name": "clientMeters", "kind": "optional", "type": "array", "description": "Detailed aggregation groups with comprehensive customer dimension breakdowns and time-series data", "modelRef": "#/components/schemas/usage.DetailedMeterAggregation.DetailedMeterAggregationGroup.out", "customType": "usage.DetailedMeterAggregation.DetailedMeterAggregationGroup.out[]", "schema": [ { "name": "group", "kind": "optional", "type": "object", "description": "Dimension information defining how this aggregation group is organized by customer attributes", "modelRef": "#/components/schemas/usage.MeterAggregation.GroupInfo.out", "customType": "usage.MeterAggregation.GroupInfo.out", "schema": [ { "name": "groupInfo", "kind": "optional", "type": "map", "description": "Map of dimension names to values used for grouping meter aggregations by customer attributes", "example": "", "customType": "map", "schema": [] } ] }, { "name": "groupValue", "kind": "optional", "type": "number", "description": "Total aggregated value for this group across all time periods in the query range", "example": "" }, { "name": "values", "kind": "optional", "type": "array", "description": "Time-series of detailed aggregated values with percentage changes for trend analysis", "modelRef": "#/components/schemas/usage.DetailedMeterAggregation.DetailedAggregationValue.out", "customType": "usage.DetailedMeterAggregation.DetailedAggregationValue.out[]", "schema": [ { "name": "value", "kind": "optional", "type": "number", "description": "Computed aggregated measurement value for the meter at the specified time point", "example": "" }, { "name": "secondsSinceEpochUtc", "kind": "optional", "type": "integer", "description": "UTC timestamp in seconds since epoch when this aggregated value was recorded", "example": 0 }, { "name": "percentageFromPrevious", "kind": "optional", "type": "number", "description": "Percentage change from the previous time period for trend analysis", "example": "" } ] }, { "name": "forecastValues", "kind": "optional", "type": "array", "description": "Predicted future detailed values with percentage projections based on historical patterns", "modelRef": "#/components/schemas/usage.DetailedMeterAggregation.DetailedAggregationValue.out", "customType": "usage.DetailedMeterAggregation.DetailedAggregationValue.out[]", "schema": [ { "name": "value", "kind": "optional", "type": "number", "description": "Computed aggregated measurement value for the meter at the specified time point", "example": "" }, { "name": "secondsSinceEpochUtc", "kind": "optional", "type": "integer", "description": "UTC timestamp in seconds since epoch when this aggregated value was recorded", "example": 0 }, { "name": "percentageFromPrevious", "kind": "optional", "type": "number", "description": "Percentage change from the previous time period for trend analysis", "example": "" } ] } ] } ], "modelRef": "#/components/schemas/usage.DetailedMeterAggregation.out", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "LYMgoTCAhXOzdf_W0lKD3", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://app.amberflo.io/usage \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n }'" }, { "id": "7CMWYnffFE_MRsQFkDDg7", "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 \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\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/usage\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "i231JAR470-rtPQcXNfkJ", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/usage\")\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 \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "6uR3FksVTM0hBwvUYoOyx", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/usage\"\n\npayload = json.dumps({\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\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": "LYMgoTCAhXOzdf_W0lKD3" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Successful request\n{\n \"metadata\": {\n \"account\": \"\",\n \"meterApiName\": \"\",\n \"aggregation\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n },\n \"filter\": \"\",\n \"groupBy\": [\n \"\"\n ],\n \"take\": {\n \"limit\": \"\",\n \"isAscending\": false\n },\n \"timeGroupingInterval\": \"\",\n \"valuesTimeGroupingInterval\": \"\",\n \"rescaleFunction\": {\n \"function\": \"\",\n \"coefficient\": 0\n },\n \"forecast\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n }\n },\n \"secondsSinceEpochIntervals\": [\n 0\n ],\n \"clientMeters\": [\n {\n \"group\": {\n \"groupInfo\": \"\"\n },\n \"groupValue\": 0,\n \"values\": [\n {\n \"value\": 0,\n \"secondsSinceEpochUtc\": \"\",\n \"percentageFromPrevious\": 0\n }\n ],\n \"forecastValues\": [\n {\n \"value\": 0,\n \"secondsSinceEpochUtc\": \"\",\n \"percentageFromPrevious\": 0\n }\n ]\n }\n ]\n}" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "", "id": "R4rQdpJFFUC6ZVkgdxgSl" } ] }