Send data through the API as JSON

POST records to CloudZero through the API to create or update a Unit Cost Metric or an Allocation Stream. About 10 minutes for your first call, plus up to 24 hours for ingest. If you're not sure whether the API or a CSV upload fits, see Send unit cost and allocation data.

Prepare your records

Each record represents one measurement at one point in time. POST a records array containing one or more records.

associated_cost (Unit Cost) and filter (Allocation) work like filter columns in CSV uploads: they scope each record to a specific subset of spend. For example, an Environment filter with values production and development lets you send separate records for each environment, even when other fields are identical.

All records in a single POST must use the same set of filter keys. Mix filter shapes by sending separate POSTs.

Sample payloads

Unit Cost Metric (cost per customer order, filtered by engineering team):

{
  "records": [
    { "timestamp": "2024-09-01", "value": 2717, "associated_cost": { "custom:Engineering Team": "Leonardo" } },
    { "timestamp": "2024-09-01", "value": 2779, "associated_cost": { "custom:Engineering Team": "Raphael" } },
    { "timestamp": "2024-09-01", "value": 6242, "associated_cost": { "custom:Engineering Team": "Michelangelo" } }
  ]
}

Allocation Stream (split a shared database cost across products):

{
  "records": [
    { "timestamp": "2024-09-01", "granularity": "DAILY", "value": 100045, "element_name": "Email" },
    { "timestamp": "2024-09-01", "granularity": "DAILY", "value": 1000600, "element_name": "Messaging" }
  ]
}

For more payload patterns (multiple Dimensions, derived Dimensions, multi-stream setups), see Telemetry API examples.

Send through the API

1. Get an API key. See Creating a new API key.

2. Choose your endpoint based on stream type:

   • Unit Cost Metric: https://api.cloudzero.com/unit-cost/v1/telemetry/metric/<stream-name>/sum
   • Allocation Stream: https://api.cloudzero.com/unit-cost/v1/telemetry/allocation/<stream-name>/sum

   Replace <stream-name> with your stream's name. CloudZero creates the stream automatically on your first POST if it doesn't already exist.

3. POST your records with the API key in the Authorization header:

   Bash

   curl -X POST \
     https://api.cloudzero.com/unit-cost/v1/telemetry/metric/engineering-team-orders/sum \
     -H "Authorization: <YOUR_API_KEY>" \
     -H "Content-Type: application/json" \
     -d @your-payload.json

   The header takes the API key directly. Don't add a Bearer prefix.

   Response codes:

   Code	Meaning	What to do
   200	Records accepted	Move on.
   400	Invalid JSON, schema, or timestamp	Check the request body against the field rules above.
   403	API key not authorized	Verify the key and the Authorization header format.
   429	Rate limit hit	Reduce request frequency, then retry.
   503	Service unavailable	Retry with exponential backoff.

4. Check Settings > Telemetry Streams for your stream's status.

After sending

Your stream appears on the Telemetry Streams page with Pending status. Within 24 hours, the status changes to Available and your data is ready to use:

• Unit Cost Metrics appear in Analytics Dashboards under Unit Metrics > [your stream name] and can be queried in plain English in AI Hub.
• Allocation Streams can be referenced in Splitting Shared Costs using AllocateByStreams.

For ingest status meanings, error troubleshooting, and stream deletion, see Manage and troubleshoot streams.

Update or replace records

The same endpoint path supports three operations. Swap /sum with /replace or /delete in the URL:

• /sum adds records or accumulates values into matching records (default for first-time sends)
• /replace overwrites existing records with new values
• /delete removes records

For full request schemas and response codes, see the API reference for Unit Cost endpoints and Allocation endpoints.