Create a new meter

1 min

POST

https://app.amberflo.io/meters

Creates a new meter definition for tracking usage events.

Required fields:

label: Display name for the dashboard
meterApiName: Technical identifier used for event ingestion (immutable after creation)
meterType: COUNT, CONTINUOUS, or UNIQUE_COUNT

Optional configuration:

dimensions: Array of dimension names for event metadata categorization
aggregation: Override default aggregation function (SUM, MAX, MIN, etc.)
useInBilling: Set to true if this meter will be used for billing calculations

Returns the created meter with generated ID and applied default settings.

Body Parameters

bodymeter_definition.MeterDefinition.in
Description
Input schema for creating or updating meter configurations with aggregation and calculation rules
- idstring
  Description
  System-generated unique identifier for updating existing meter definition records.
- meterApiNamestringrequired
  Description
  Technical identifier used when ingesting events and querying usage data through APIs. It must be at most 50 chars long. Only `_`, `-`, `.` and alphanumeric chars are allowed.
- labelstringrequired
  Description
  Human-readable display name shown in dashboard interfaces. Must be unique within account. Note that the following characters are not allowed: `/`, `"`, `=`, `<`, `>`.
- descriptionstring
  Description
  Detailed explanation of meter purpose and usage displayed in user interfaces. Note that the following characters are not allowed: `=`, `<`, `>`.
- lockingStatuscommon.LockingStatus.in
  Description
  Current modification status controlling whether meter configuration can be changed or deleted. - `open` allows all modifications; - `close_to_deletion` forbids deleting the meter and changing its meterApiName; - `close_to_changes` and `deprecated` forbid any modification. Default: `open`
- meterTypemeter_definition.MeterType.inrequired
  Description
  Classification determining how usage events are measured and aggregated over time. Note that the following meter types have been deprecated: - `avg_of_all_usage` - `resource_leasing` - `max_usage` - `running_total` - `unique_count` - `last_resource_status` - `duration_snapshot`
- dimensionsstring[]
  Description
  Custom attributes used for filtering and grouping usage data in queries and reports. Dimension names must be at most 30 chars long. Only `-`, `.` and alphanumeric chars are allowed.
- aggregationDimensionsstring[]
  Description
  Subset of dimensions used for aggregations, typically identifying unique resources or events.
- useInBillingboolean
  Description
  Whether to automatically create and sync a product item for billing integration. When set to `true`, a product item will be created for this meter, if needed, and its name and description will be set to the meter's label and description. Note that you cannot delete a meter if the associated product item cannot be deleted too.
- squashSumMeterboolean
  Description
  Whether to combine events with identical dimensions into cumulative hourly records during ingestion. This way all meter events with same dimensions will be reduced to one cummulative record in that hour. Note that only `sum_of_all_usage` meters can have this flag set to `true`.
- sharedWithPartnersboolean
  Description
  Whether this meter configuration is accessible to partner accounts for usage tracking.
- enabledboolean
  Description
  Whether this meter actively processes incoming events or remains inactive for configuration.
- timeoutInMinutesinteger<int32>
  Description
  Duration to consider events or resources active without new meter event ingestion. Note this is not applicable for `sum_of_all_usage`, `avg_of_all_usage` and `active_users` meters. For all others, the default is 1 year.
- viewGroupingFunctionmeter_definition.ViewGroupingFunction.in
  Description
  Default mathematical function for grouping usage data in dashboard and report views.
- viewGroupingIntervalmeter_definition.ViewGroupingInterval.in
  Description
  Default time interval for grouping usage data in dashboard and report displays.
- viewRescaleFunctionmeter_definition.RescaleFunction.in
  Description
  Default function used by Usage API to adjust the numerical scale of returned usage values.
  - functionmeter_definition.RescaleFunctionType.in
    Description
    Mathematical operation used to transform usage values before display or billing calculations. `MULTIPLY` means that reported usage = coefficient * actual usage
  - coefficientnumber
    Description
    Numerical factor applied by the rescale function to transform the original usage values.
- deduplicationConfigmeter_definition.MeterDeduplicationConfig.in
  Description
  Configuration rules for identifying and removing duplicate events during meter processing.
  - lookBackTimeInDaysinteger<int32>
    Description
    Time window in days for considering an event a duplicate. If two events with identical deduplication dimension values are sent within this period, the second event will be discarded.
  - dimensionsstring[]
    Description
    Subset of meter dimensions used to identify duplicate events. Must contain at least one dimension.

Responses

200Successful request

meter_definition.MeterDefinition.out
Description
Complete meter configuration defining how usage events are aggregated, grouped, and calculated for billing purposes
- accountIdstring
  Description
  Unique identifier of the account that owns this meter configuration.
- replicatedFromAccountIdstring
  Description
  Source account identifier when this meter was replicated from another account.
- idstring
  Description
  System-generated unique identifier for this meter definition record.
- meterApiNamestringrequired
  Description
  Technical identifier used when ingesting events and querying usage data through APIs. It must be at most 50 chars long. Only `_`, `-`, `.` and alphanumeric chars are allowed.
- labelstringrequired
  Description
  Human-readable display name shown in dashboard interfaces. Must be unique within account. Note that the following characters are not allowed: `/`, `"`, `=`, `<`, `>`.
- descriptionstring
  Description
  Detailed explanation of meter purpose and usage displayed in user interfaces. Note that the following characters are not allowed: `=`, `<`, `>`.
- lockingStatuscommon.LockingStatus.out
  Description
  Current modification status controlling whether meter configuration can be changed or deleted. - `open` allows all modifications; - `close_to_deletion` forbids deleting the meter and changing its meterApiName; - `close_to_changes` and `deprecated` forbid any modification. Default: `open`
- meterTypemeter_definition.MeterType.outrequired
  Description
  Classification determining how usage events are measured and aggregated over time. Note that the following meter types have been deprecated: - `avg_of_all_usage` - `resource_leasing` - `max_usage` - `running_total` - `unique_count` - `last_resource_status` - `duration_snapshot`
- aggregationmeter_definition.AggregationType.out
  Description
  Mathematical function applied to aggregate individual usage events into meter values.
- eventTypecommon.meter_definition.EventType.out
  Description
  Classification of events processed by this meter for internal routing and handling.
- dimensionsstring[]
  Description
  Custom attributes used for filtering and grouping usage data in queries and reports. Dimension names must be at most 30 chars long. Only `-`, `.` and alphanumeric chars are allowed.
- aggregationDimensionsstring[]
  Description
  Subset of dimensions used for aggregations, typically identifying unique resources or events.
- useInBillingboolean
  Description
  Whether to automatically create and sync a product item for billing integration. When set to `true`, a product item will be created for this meter, if needed, and its name and description will be set to the meter's label and description. Note that you cannot delete a meter if the associated product item cannot be deleted too.
- unitOfUsageboolean
  Description
  Internal flag indicating this meter derives usage from another meter using unit conversions.
- ultraFrequencyUniqueMeterboolean
  Description
  Internal optimization flag for meters processing extremely high-frequency unique event streams.
- seatBasedboolean
  Description
  Warning: Deprecated Legacy flag indicating sum meter usage for seat-based billing scenarios over invoices.
- squashSumMeterboolean
  Description
  Whether to combine events with identical dimensions into cumulative hourly records during ingestion. This way all meter events with same dimensions will be reduced to one cummulative record in that hour. Note that only `sum_of_all_usage` meters can have this flag set to `true`.
- sharedWithPartnersboolean
  Description
  Whether this meter configuration is accessible to partner accounts for usage tracking.
- enabledboolean
  Description
  Whether this meter actively processes incoming events or remains inactive for configuration.
- timeoutInMinutesinteger<int32>
  Description
  Duration to consider events or resources active without new meter event ingestion. Note this is not applicable for `sum_of_all_usage`, `avg_of_all_usage` and `active_users` meters. For all others, the default is 1 year.
- viewGroupingFunctionmeter_definition.ViewGroupingFunction.out
  Description
  Default mathematical function for grouping usage data in dashboard and report views.
- viewGroupingIntervalmeter_definition.ViewGroupingInterval.out
  Description
  Default time interval for grouping usage data in dashboard and report displays.
- viewRescaleFunctionmeter_definition.RescaleFunction.out
  Description
  Default function used by Usage API to adjust the numerical scale of returned usage values.
  - functionmeter_definition.RescaleFunctionType.out
    Description
    Mathematical operation used to transform usage values before display or billing calculations. `MULTIPLY` means that reported usage = coefficient * actual usage
  - coefficientnumber
    Description
    Numerical factor applied by the rescale function to transform the original usage values.
- statisticsmeter_definition.MeterStatistics.out
  Description
  Computed statistical information about meter usage patterns and event frequencies.
  - highFrequencyboolean
    Description
    Whether this meter processes events at high frequency requiring special optimization handling.
  - highCardinalityInfomap<string, meter_definition.MeterStatisticsInfo.out>
    Description
    Statistical information about dimensions with high cardinality that may impact performance.
  - frequencymeter_definition.MeterStatisticsInfo.out
    Description
    Statistical information about the overall event frequency patterns for this meter.
    - valuesPerHournumber
      Description
      Average number of events processed per hour for this meter or dimension.
    - standardDeviationnumber
      Description
      Statistical measure of variance in event frequency patterns over time.
- deduplicationConfigmeter_definition.MeterDeduplicationConfig.out
  Description
  Configuration rules for identifying and removing duplicate events during meter processing.
  - lookBackTimeInDaysinteger<int32>
    Description
    Time window in days for considering an event a duplicate. If two events with identical deduplication dimension values are sent within this period, the second event will be discarded.
  - dimensionsstring[]
    Description
    Subset of meter dimensions used to identify duplicate events. Must contain at least one dimension.
- dimensionMetadatamap<string, meter_definition.DimensionMetadata.out>
  Description
  Additional configuration and metadata associated with each dimension used by this meter.
- dimensionValuePatternsmap<string, string>
  Description
  Regular expression patterns for validating dimension values during event ingestion.
- createTimeinteger<int64>
  Description
  Creation time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)
- updateTimeinteger<int64>
  Description
  Update time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)

curl

curl --request POST \
     --url https://app.amberflo.io/meters \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "meterApiName": "",
     "label": "",
     "meterType": ""
     }'

javascript

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

var raw = JSON.stringify({
   "meterApiName": "",
   "label": "",
   "meterType": ""
});

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

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

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": "",
   "label": "",
   "meterType": ""
})

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

python

import requests
import json

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

payload = json.dumps({
   "meterApiName": "",
   "label": "",
   "meterType": ""
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

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

print(response.text)

200

// Successful request
{
  "accountId": "",
  "replicatedFromAccountId": "",
  "id": "",
  "meterApiName": "",
  "label": "",
  "description": "",
  "lockingStatus": "",
  "meterType": "",
  "aggregation": "",
  "eventType": "",
  "dimensions": [
    ""
  ],
  "aggregationDimensions": [
    ""
  ],
  "useInBilling": false,
  "unitOfUsage": false,
  "ultraFrequencyUniqueMeter": false,
  "seatBased": false,
  "squashSumMeter": false,
  "sharedWithPartners": false,
  "enabled": false,
  "timeoutInMinutes": "",
  "viewGroupingFunction": "",
  "viewGroupingInterval": "",
  "viewRescaleFunction": {
    "function": "",
    "coefficient": 0
  },
  "statistics": {
    "highFrequency": false,
    "highCardinalityInfo": "",
    "frequency": {
      "valuesPerHour": 0,
      "standardDeviation": 0
    }
  },
  "deduplicationConfig": {
    "lookBackTimeInDays": "",
    "dimensions": [
      ""
    ]
  },
  "dimensionMetadata": "",
  "dimensionValuePatterns": "",
  "createTime": "",
  "updateTime": ""
}