The telemetry endpoint allows you to send additional usage data to the CloudZero system to better allocate cloud spend. The most common use cases for telemetry is to break down shared resources for allocation among teams, customers, features and the such.

The Telemetry endpoint supports a very flexible data model in which you can target any portion of your cloud spend and represent usage of the systems generating that spend by sending records saying that "named elements" consumed a certain amount of that infrastructure or cloud spend.


CloudZero Telemetry API Endpoint

API Authorization

  1. You can obtain a CloudZero API Key from
  2. Add an Authorization: <cloudzero-api-key> header to each request


  • Each organization can send up 1m records per day and 300k records per minute
  • Max request size: there is a 5MB size limit per request, meaning the API will accept up to approximately 10,000 records of 512 bytes each
  • When sending a large number of individual requests very rapidly, the API may return a 503 "slow down" error; you can address this by either adding a delayed retry or by batching larger numbers of records into fewer requests


For example, if you wanted to transmit the activity for the customer Hooli on January 25th, 2021, during the whole day, where your billing feature processed 250M records you would send.

  "records": [
    	"timestamp": "2020-01-25T00:00:00Z",
    	"granularity": "DAILY",
    	"filter": {
      	"custom:feature": [
      	"tag:environment": [
        "tag:owner": [
    	"element-name": "<HOOLI-CUSTOMER-ID>",
    	"telemetry-stream": "billing-records-processed",
    	"value": "250000000"


Filter Limitations

  • Each telemetry record can’t have more than 5 filter keys and each set of values can’t have more than 20 values.
  • When multiple filter values are specified, those values are aggregated together. When multiple types of filter keys are present, those types of filters are combined using the intersection.
  • For example: { "account": ["1", "2"], "service": ["A"] } translates to WHERE (account = “1” OR account = “2”) AND service = “A”
  • All records within a telemetry-stream must have the same set of keys defined in their filter.