Telemetry API examples

The following examples show how to structure API payloads for different unit cost scenarios. Each example includes the JSON payload format and an explanation of when to use it.

Single metric, no Dimensions

Scenario: You want to track cost per daily active user across your entire platform.

{
  "records": [
      {
        "timestamp": "2023-11-07",
        "value": 10011
      }
   ]
}

The stream path for this example: https://api.cloudzero.com/unit-cost/v1/telemetry/metric/daily-active-user

The stream name is derived from the path parameter. For details, see the Unit Metric API documentation.

Single metric with one Dimension

Scenario: You want to track cost per API call broken out by service using a custom Company Services Dimension.

For the metric to filter correctly when the Dimension is used in a Dashboard, each record must include the appropriate associated_cost value.

{
  "records": [
    {
      "timestamp": "2023-11-06",
      "associated_cost": {
        "custom:Company Services": "aggregation"
      },
      "value": 10011
    },
    {
      "timestamp": "2023-11-07",
      "associated_cost": {
        "custom:Company Services": "streaming"
      },
      "value": 458.33
    },
    {
      "timestamp": "2023-11-06",
      "associated_cost": {
        "custom:Company Services": "allocate"
      },
      "value": 112.53
    },
    {
      "timestamp": "2023-11-07",
      "associated_cost": {
        "custom:Company Services": "budget"
      },
      "value": 225
    }
   ]
}

Each record includes a single value (number of API calls) associated with a different value in the Company Services Dimension.

Multiple streams with one Dimension

Scenario: You are a video streaming service and want to track both cost per user and total plays per user, broken out by user type (logged-in vs anonymous).

This requires two separate streams, each including the User Type Dimension in the associated_cost field.

Stream: total-streams-by-day

{
  "records": [
      {
        "timestamp": "2023-11-06",
        "associated_cost": {
          "custom:User Type": "logged-in"
        },
        "value": 591063.958333333
      }
   ]
}

Stream: total-users-by-day

{
  "records": [
      {
        "timestamp": "2023-11-06",
        "associated_cost": {
          "custom:User Type": "anonymous"
        },
        "value": 359491.333333333
      }
   ]
}

Single stream with multiple Dimensions

Scenario: You want to track cost per client per region. This requires two Dimensions in the associated_cost field: Client and Region.

{
  "records": [
      {
        "timestamp": "2023-11-01",
        "associated_cost": {
          "custom:Client": "Client 123",
          "Region": "Australia"
        },
        "value": 84
      },
      {
        "timestamp": "2023-11-01",
        "associated_cost": {
          "custom:Client": "Client 456",
          "Region": "Europe"
        },
        "value": 2978
      },
      {
        "timestamp": "2023-11-01",
        "associated_cost": {
          "custom:Client": "Client 789",
          "Region": "North America"
        },
        "value": 26
      }
   ]
}

ℹ️
When using a CloudZero built-in Dimension (like Region), do not include the custom: prefix. Use the custom: prefix only for Organization Dimensions.

Derived Dimensions

Scenario: You want to track cost per API call by customer. You have a CustomerID Dimension and a separate CustomerName Dimension derived from CustomerID.

{
  "records": [
      {
        "timestamp": "2023-12-07",
        "associated_cost": {
          "custom:CustomerID": "743e5233-82a1-42e0-a7a0-c66ac6778558"
        },
        "value": 999
      }
   ]
}

If you expect the CustomerName Dimension to also filter the metric data, you must explicitly include it in the associated_cost field. Derived Dimensions are not automatically resolved from their parent Dimension.

⚠️
Any Dimension you associate with a metric must be as static as possible. If a value changes in the underlying data (for example, a customer changes their ID), historical records sent with the previous value are not automatically updated. This applies to modifications only, not additions.

ℹ️
Have questions or feedback? Reach out to your account manager.