---
title: "Post telemetry records"
method: POST
path: "/unit-cost/v1/telemetry/allocation/{telemetry_stream_name}"
tags: ["telemetry"]
---

# Post telemetry records

`POST /unit-cost/v1/telemetry/allocation/{telemetry_stream_name}`

Allocation telemetry provides additional information that the CloudZero system can use to split your cloud cost data through custom allocation dimensions. In this way, you can gain further insights into the costs of your multi-tenant systems, shared infrastructure, and more.

The `telemetry_stream_name` sent to this API can be used in the `Streams` parameter of an `AllocateByStreams`
custom dimension (see https://docs.cloudzero.com/docs/allocation-short-form-rules#allocatebystreams-short-form-rule)


**Note**: This endpoint is the legacy version of `/unit-cost/v1/telemetry/allocation/{telemetry_stream_name}/sum`. It is functionally identical, but predates the operational path parameter concept.

## Path parameters

- `telemetry_stream_name` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `records` AllocationTelemetryRecord[], required — A batch of telemetry records to submit to CloudZero.
    - `value` number, required — The value associated with this allocation telemetry record (e.g., the number of requests, GBs, etc. of system usage that this record represents). Must be greater than or equal to 0. On send (sum) operations, records with a value of 0 are accepted but do not contribute to aggregated telemetry, so they will not appear in the resulting data. The `replace` and `replace_period` operations reject zero-value records with a 400; use the delete operation to remove a record.
    - `timestamp` string, required — ISO formatted timestamp of when the usage occurred.
    - `granularity` 'HOURLY' | 'DAILY' | 'MONTHLY', required — The sample frequency over time.
    - `element_name` string, required — This is used to attribute usage to a specific customer, product, tenant, or other entity. Use either a generated UUID or a human-readable name. This value will become an element of any allocation dimension in which this telemetry stream is used. **Aliases:** The API also accepts `id` or `element-name` as alternative field names for this property.
    - `filter` Filter, required — A definition of the portion of your infrastructure to which this allocation telemetry corresponds. Defined as a mapping from CloudZero Dimensions to lists of values, where dimensions are identified similarly to how they would be in the `partitions` parameter of a CloudZero Explorer URL (https://app.cloudzero.com/explorer). For example, - custom:<the name of your CloudZero Custom Dimension> (as defined in CostFormation via the Name parameter) - tag:<your cloud provider tag key> - k8s_label:<your Kubernetes label key> - accounts, services, product_family, ... - k8s_cluster, k8s_namespace, ... **Note:** `"filter": "*"` or the empty filter set `"filter": {}` will apply this telemetry to all of your spend. **Alias:** The API also accepts `target` as an alternative field name for this property.

## Response `200`

Telemetry accepted

## Other responses

- `400` — Invalid request, specific responses for: - Invalid JSON - Invalid Schema: Unrecognized filter keys - Invalid Schema: Missing required fields - Timestamp too far into the future - All records in a stream must contain the same filter keys - All records in a stream must contain the same granularity as the stream's granularity
- `403` — Not authorized, make sure you're using a valid API key in the header `Authorization`
- `429` — Rate limit exceeded. The API enforces rate limiting on incoming requests. Retry after a short delay.
- `503` — Service temporarily unavailable due to downstream capacity constraints. Retry after a short delay with exponential backoff.

---

[API](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources.md) · [All operations](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cloudzero/cloudzero-api-v2-resources/revisions/fd805a0e75e5/schema)