The CloudZero Unit Metric Telemetry API allows you to send unit cost data related to your system's operations. You can read more about this data in the Unit Cost Analytics section of the documentation.


CloudZero Unit Metric Endpoint{metric_name}

{metric_name}: is the user defined name to associate with this Unit Metric.

General Telemetry API information and limitations can be found on the Telemetry section of this documentation.


The following metric telemetry record specifies some system activity -- a count of audio streams on December 7, 2023, when 12,325 people listened to a particular sea star attempt to play mayonnaise as an instrument.

  "records": [
      "timestamp": "2023-12-07T00:00:00",
      "value": 12345,
          "custom:Client": "Patric Star",
          "custom:Product": "Mayonaise",
          "custom:Product Group": "Instruments"

For additional examples and case studies, please see Unit Metric Case Studies


  • timestamp: ISO formatted date and time. Time can be included in this data, but will be ignored. All telemetry is at daily granularity. Time will be converted to UTC.

  • value : the metric to associate. This is a number - decimals are allowed but not required and do not include commas.

    We support 15 significant digits for the value. i.e. value is rounded to the 15th significant digit

  • associated_cost : (optional) a dictionary of CloudZero dimensions which further categorize the cost data such that the resulting unit metric can be filtered.

    • The keys and values in the associated_cost list must appear in this format: <Dimension Name>: <Dimension Value>

      • The <Dimension Name> is the human readable display name of your dimension. If the dimension you are referencing is custom (that is, not a dimension native to CloudZero), then it must include the custom: prefix.

        For example, if you made a custom dimension called My Awesome Dimension, then your <Dimension Name> would be custom:My Awesome Dimension.

        If the dimension you wanted to filter by is the CloudZero Region dimension, then your <Dimension Name> would simply be Region.

      • The <Dimension Value> must be a single value for the dimension. The value must be a string and it may not be a list.


  • Granularity is always daily. You may send data in at a higher granularity, but the data will be aggregated together to the day.

  • You may only associate 5 associated_cost dimensions with a Unit Metric.

    • All records within a stream must have the same set of dimensions defined in their associated cost parameter.