---
title: Get a meter by id
slug: reference/get-a-meter-by-id
docTags:
createdAt: 2025-07-10T21:22:02.138Z
---
{
"id": "xBBXObjqVVQlE7gcg7iLr",
"type": "api-oas-v2",
"data": {
"method": "GET",
"url": "https://app.amberflo.io/meters/{id}",
"servers": [
{
"url": "https://app.amberflo.io/meters/{id}"
}
],
"name": "Get a meter by id",
"description": "Returns the meter definition for the specified ID.
\nThe response includes complete configuration details: meter type, aggregation function, dimensions, locking status, usage statistics, and billing settings. Use this endpoint to retrieve current meter configuration before making updates or to validate meter settings.
",
"contentType": "application/json",
"request": {
"pathParameters": [
{
"kind": "required",
"name": "id",
"type": "string",
"description": "Unique identifier of the meter to retrieve. Must be a valid meter ID that exists in your account."
}
],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [],
"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": "Complete meter configuration defining how usage events are aggregated, grouped, and calculated for billing purposes",
"customType": "meter_definition.MeterDefinition.out",
"schema": [
{
"name": "accountId",
"kind": "optional",
"type": "string",
"description": "Unique identifier of the account that owns this meter configuration.",
"example": ""
},
{
"name": "replicatedFromAccountId",
"kind": "optional",
"type": "string",
"description": "Source account identifier when this meter was replicated from another account.",
"example": ""
},
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "System-generated unique identifier for this meter definition record.",
"example": ""
},
{
"name": "meterApiName",
"kind": "required",
"type": "string",
"description": "Technical identifier used when ingesting events and querying usage data through APIs.\n\nIt must be at most 50 chars long. Only `_`, `-`, `.` and alphanumeric chars are allowed.",
"example": ""
},
{
"name": "label",
"kind": "required",
"type": "string",
"description": "Human-readable display name shown in dashboard interfaces. Must be unique within account.\n\nNote that the following characters are not allowed: `/`, `\"`, `=`, `<`, `>`.",
"example": ""
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Detailed explanation of meter purpose and usage displayed in user interfaces.\n\nNote that the following characters are not allowed: `=`, `<`, `>`.",
"example": ""
},
{
"name": "lockingStatus",
"kind": "optional",
"type": "string",
"description": "Current modification status controlling whether meter configuration can be changed or deleted.\n\n- `open` allows all modifications;\n- `close_to_deletion` forbids deleting the meter and changing its meterApiName;\n- `close_to_changes` and `deprecated` forbid any modification.\n\nDefault: `open`\n",
"modelRef": "#/components/schemas/common.LockingStatus.out",
"customType": "common.LockingStatus.out",
"schema": []
},
{
"name": "meterType",
"kind": "required",
"type": "string",
"description": "Classification determining how usage events are measured and aggregated over time.\n\nNote that the following meter types have been deprecated:\n- `avg_of_all_usage`\n- `resource_leasing`\n- `max_usage`\n- `running_total`\n- `unique_count`\n- `last_resource_status`\n- `duration_snapshot`\n",
"modelRef": "#/components/schemas/meter_definition.MeterType.out",
"customType": "meter_definition.MeterType.out",
"schema": []
},
{
"name": "aggregation",
"kind": "optional",
"type": "string",
"description": "Mathematical function applied to aggregate individual usage events into meter values.",
"modelRef": "#/components/schemas/meter_definition.AggregationType.out",
"customType": "meter_definition.AggregationType.out",
"schema": []
},
{
"name": "eventType",
"kind": "optional",
"type": "string",
"description": "Classification of events processed by this meter for internal routing and handling.",
"modelRef": "#/components/schemas/common.meter_definition.EventType.out",
"customType": "common.meter_definition.EventType.out",
"schema": []
},
{
"name": "dimensions",
"kind": "optional",
"type": "array",
"description": "Custom attributes used for filtering and grouping usage data in queries and reports.\n\nDimension names must be at most 30 chars long. Only `-`, `.` and alphanumeric chars are allowed.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "aggregationDimensions",
"kind": "optional",
"type": "array",
"description": "Subset of dimensions used for aggregations, typically identifying unique resources or events.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "useInBilling",
"kind": "optional",
"type": "boolean",
"description": "Whether to automatically create and sync a product item for billing integration.\n\nWhen 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.\n\nNote that you cannot delete a meter if the associated product item cannot be deleted too.",
"example": ""
},
{
"name": "unitOfUsage",
"kind": "optional",
"type": "boolean",
"description": "Internal flag indicating this meter derives usage from another meter using unit conversions.",
"example": ""
},
{
"name": "ultraFrequencyUniqueMeter",
"kind": "optional",
"type": "boolean",
"description": "Internal optimization flag for meters processing extremely high-frequency unique event streams.",
"example": ""
},
{
"name": "seatBased",
"kind": "optional",
"type": "boolean",
"deprecated": true,
"description": "Warning: Deprecated\nLegacy flag indicating sum meter usage for seat-based billing scenarios over invoices.",
"example": ""
},
{
"name": "squashSumMeter",
"kind": "optional",
"type": "boolean",
"description": "Whether to combine events with identical dimensions into cumulative hourly records during ingestion.\n\nThis way all meter events with same dimensions will be reduced to one cummulative record in that hour.\n\nNote that only `sum_of_all_usage` meters can have this flag set to `true`.",
"example": ""
},
{
"name": "sharedWithPartners",
"kind": "optional",
"type": "boolean",
"description": "Whether this meter configuration is accessible to partner accounts for usage tracking.",
"example": ""
},
{
"name": "enabled",
"kind": "optional",
"type": "boolean",
"description": "Whether this meter actively processes incoming events or remains inactive for configuration.",
"example": ""
},
{
"name": "timeoutInMinutes",
"kind": "optional",
"type": "integer",
"description": "Duration to consider events or resources active without new meter event ingestion.\n\nNote 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.",
"example": 0
},
{
"name": "viewGroupingFunction",
"kind": "optional",
"type": "string",
"description": "Default mathematical function for grouping usage data in dashboard and report views.",
"modelRef": "#/components/schemas/meter_definition.ViewGroupingFunction.out",
"customType": "meter_definition.ViewGroupingFunction.out",
"schema": []
},
{
"name": "viewGroupingInterval",
"kind": "optional",
"type": "string",
"description": "Default time interval for grouping usage data in dashboard and report displays.",
"modelRef": "#/components/schemas/meter_definition.ViewGroupingInterval.out",
"customType": "meter_definition.ViewGroupingInterval.out",
"schema": []
},
{
"name": "viewRescaleFunction",
"kind": "optional",
"type": "object",
"description": "Default function used by Usage API to adjust the numerical scale of returned usage values.",
"modelRef": "#/components/schemas/meter_definition.RescaleFunction.out",
"customType": "meter_definition.RescaleFunction.out",
"schema": [
{
"name": "function",
"kind": "optional",
"type": "string",
"description": "Mathematical operation used to transform usage values before display or billing calculations.\n\n`MULTIPLY` means that reported usage = coefficient * actual usage",
"modelRef": "#/components/schemas/meter_definition.RescaleFunctionType.out",
"customType": "meter_definition.RescaleFunctionType.out",
"schema": []
},
{
"name": "coefficient",
"kind": "optional",
"type": "number",
"description": "Numerical factor applied by the rescale function to transform the original usage values.",
"example": ""
}
]
},
{
"name": "statistics",
"kind": "optional",
"type": "object",
"description": "Computed statistical information about meter usage patterns and event frequencies.",
"modelRef": "#/components/schemas/meter_definition.MeterStatistics.out",
"customType": "meter_definition.MeterStatistics.out",
"schema": [
{
"name": "highFrequency",
"kind": "optional",
"type": "boolean",
"description": "Whether this meter processes events at high frequency requiring special optimization handling.",
"example": ""
},
{
"name": "highCardinalityInfo",
"kind": "optional",
"type": "map",
"description": "Statistical information about dimensions with high cardinality that may impact performance.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "frequency",
"kind": "optional",
"type": "object",
"description": "Statistical information about the overall event frequency patterns for this meter.",
"modelRef": "#/components/schemas/meter_definition.MeterStatisticsInfo.out",
"customType": "meter_definition.MeterStatisticsInfo.out",
"schema": [
{
"name": "valuesPerHour",
"kind": "optional",
"type": "number",
"description": "Average number of events processed per hour for this meter or dimension.",
"example": ""
},
{
"name": "standardDeviation",
"kind": "optional",
"type": "number",
"description": "Statistical measure of variance in event frequency patterns over time.",
"example": ""
}
]
}
]
},
{
"name": "deduplicationConfig",
"kind": "optional",
"type": "object",
"description": "Configuration rules for identifying and removing duplicate events during meter processing.",
"modelRef": "#/components/schemas/meter_definition.MeterDeduplicationConfig.out",
"customType": "meter_definition.MeterDeduplicationConfig.out",
"schema": [
{
"name": "lookBackTimeInDays",
"kind": "optional",
"type": "integer",
"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.",
"example": 0
},
{
"name": "dimensions",
"kind": "optional",
"type": "array",
"description": "Subset of meter dimensions used to identify duplicate events. Must contain at least one dimension.",
"example": "",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
}
]
},
{
"name": "dimensionMetadata",
"kind": "optional",
"type": "map",
"description": "Additional configuration and metadata associated with each dimension used by this meter.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "dimensionValuePatterns",
"kind": "optional",
"type": "map",
"description": "Regular expression patterns for validating dimension values during event ingestion.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "createTime",
"kind": "optional",
"type": "integer",
"description": "Creation time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)",
"example": 0
},
{
"name": "updateTime",
"kind": "optional",
"type": "integer",
"description": "Update time in [Unix time](https://en.wikipedia.org/wiki/Unix_time) (milliseconds)",
"example": 0
}
],
"modelRef": "#/components/schemas/meter_definition.MeterDefinition.out",
"isExpanded": true
}
]
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "C8QgTmF1Vwc_uV0VwK8R1",
"language": "curl",
"label": "cURL",
"code": "curl --request GET \\\n --url https://app.amberflo.io/meters/{id} \\\n --header 'accept: application/json'"
},
{
"id": "hjsKqeT3mgj2dQDEtFeho",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/meters/{id}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "9G7Eldit8qStd-qh-Uk1j",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/meters/{id}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "HwtHGAkqwWFz-mGbxjUK2",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/meters/{id}\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "C8QgTmF1Vwc_uV0VwK8R1"
},
"results": {
"languages": [
{
"id": "DYU6QaArrFcyelCG2aDK2",
"language": "200",
"code": "// Successful request\n{\n \"accountId\": \"\",\n \"replicatedFromAccountId\": \"\",\n \"id\": \"\",\n \"meterApiName\": \"\",\n \"label\": \"\",\n \"description\": \"\",\n \"lockingStatus\": \"\",\n \"meterType\": \"\",\n \"aggregation\": \"\",\n \"eventType\": \"\",\n \"dimensions\": [\n \"\"\n ],\n \"aggregationDimensions\": [\n \"\"\n ],\n \"useInBilling\": false,\n \"unitOfUsage\": false,\n \"ultraFrequencyUniqueMeter\": false,\n \"seatBased\": false,\n \"squashSumMeter\": false,\n \"sharedWithPartners\": false,\n \"enabled\": false,\n \"timeoutInMinutes\": \"\",\n \"viewGroupingFunction\": \"\",\n \"viewGroupingInterval\": \"\",\n \"viewRescaleFunction\": {\n \"function\": \"\",\n \"coefficient\": 0\n },\n \"statistics\": {\n \"highFrequency\": false,\n \"highCardinalityInfo\": \"\",\n \"frequency\": {\n \"valuesPerHour\": 0,\n \"standardDeviation\": 0\n }\n },\n \"deduplicationConfig\": {\n \"lookBackTimeInDays\": \"\",\n \"dimensions\": [\n \"\"\n ]\n },\n \"dimensionMetadata\": \"\",\n \"dimensionValuePatterns\": \"\",\n \"createTime\": \"\",\n \"updateTime\": \"\"\n}"
}
],
"selectedLanguageId": "DYU6QaArrFcyelCG2aDK2"
}
},
"children": [
{
"text": "",
"id": "vzaN0JpQyCd9x8-pX3Eub"
}
]
}