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

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.

\n

Common use cases:

\n\n

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

\n

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

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "optional", "name": "body", "type": "array", "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": "array", "description": "Aggregated meter data including metadata and grouped client measurements for specific meter analysis", "customType": "usage.MeterAggregation.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": "clientMeters", "kind": "optional", "type": "array", "description": "Collection of meter aggregation groups containing computed values organized by customer dimensions", "modelRef": "#/components/schemas/usage.MeterAggregation.MeterAggregationGroup.out", "customType": "usage.MeterAggregation.MeterAggregationGroup.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 aggregated values showing usage progression over time for this group", "modelRef": "#/components/schemas/usage.MeterAggregation.AggregationValue.out", "customType": "usage.MeterAggregation.AggregationValue.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 or computed", "example": 0 } ] }, { "name": "forecastValues", "kind": "optional", "type": "array", "description": "Predicted future aggregated values based on historical patterns for this group", "modelRef": "#/components/schemas/usage.MeterAggregation.AggregationValue.out", "customType": "usage.MeterAggregation.AggregationValue.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 or computed", "example": 0 } ] } ] } ], "modelRef": "#/components/schemas/usage.MeterAggregation.out", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "example-0-curl", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://app.amberflo.io/usage/sparse/batch \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '[\n {\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n }\n ]'" }, { "id": "example-1-javascript", "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 {\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\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/sparse/batch\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "example-2-ruby", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/usage/sparse/batch\")\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 {\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\n }\n])\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "example-3-python", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/usage/sparse/batch\"\n\npayload = json.dumps([\n {\n \"meterApiName\": \"\",\n \"timeRange\": {\n \"startTimeInSeconds\": 0\n },\n \"take\": {\n \"limit\": 0\n },\n \"forecast\": {\n \"endTimeInSeconds\": 0\n }\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": "example-0-curl" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Successful request\n[\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 \"clientMeters\": [\n {\n \"group\": {\n \"groupInfo\": \"\"\n },\n \"groupValue\": 0,\n \"values\": [\n {\n \"value\": 0,\n \"secondsSinceEpochUtc\": \"\"\n }\n ],\n \"forecastValues\": [\n {\n \"value\": 0,\n \"secondsSinceEpochUtc\": \"\"\n }\n ]\n }\n ]\n }\n]" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "", "id": "6EbSDs--9J5O9mOpsX-9l" } ] }