---
title: "Replace metric records for the submitted dates"
method: POST
path: "/unit-cost/v1/telemetry/metric/{metric_name}/replace_period"
tags: ["telemetry"]
---

# Replace metric records for the submitted dates

`POST /unit-cost/v1/telemetry/metric/{metric_name}/replace_period`

Atomically replace metric telemetry records by usage date. For every date present in the submitted batch, all existing records on that date are dropped and the submitted records inserted. Dates not present in the batch are left untouched.

> ⚠️ **You must send all of a day's records in a single request.** Each submitted date is replaced *wholesale* — any record you omit for that date is dropped. Only use `replace_period` when you can send a day's complete metric telemetry at once. If you can't guarantee that, use `sum` or `replace` instead.

A value of 0 is not allowed for the `replace_period` operation and is rejected with a 400. To remove a target from a date, omit it from that date's batch; to clear records outside a batch, use the delete operation.

**Example.** A metric has records on `2024-03-05` for targets A and B, and on `2024-03-10` for target A. You submit a `replace_period` batch containing only `2024-03-05` / target A. Result: `2024-03-05` now contains only target A — target B on that date is **dropped** because it was not in the batch — while `2024-03-10` is left untouched. To keep target B on `2024-03-05`, include it in the same request.

**Note:** The unit metric must already exist when using this endpoint.

## Path parameters

- `metric_name` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `records` MetricTelemetryRecord[], required — A batch of telemetry records to submit to CloudZero.
    - `value` number, required — The value associated with this unit metric telemetry record (e.g., the number of requests, GBs, etc. that this record represents). May be negative to support use cases such as budgets (for example, refunds or budget reductions). On send (sum) operations a value of 0 is accepted but does not contribute to aggregated telemetry. 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` 'DAILY' | 'MONTHLY' — The sample frequency over time.
    - `associated_cost` AssociatedCost — A definition of the portion of your infrastructure to which this metric telemetry corresponds. When filtering on the dimensions specified here via the CloudZero platform, the corresponding unit metric's value will also be filtered. Defined as a mapping from CloudZero Dimensions to string 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, ...

## Response `201`

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 - A value of 0 is not allowed; use the delete operation to remove a record - Telemetry stream must exist in order to update telemetry records - 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`
- `404` — The telemetry stream does not exist. Streams must be created (via sum, replace, or the UI) before replace_period can target them.
- `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)