---
title: "Record Cluster Usage"
method: POST
path: "/internal/usage/clusters"
tags: ["internal"]
---

# Record Cluster Usage

`POST /internal/usage/clusters`

## Request

- Base URL: `https://api.mengi.cloud` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mengi.cloud/internal/usage/clusters`
- Auth: none declared. Required headers: `x-service-token`

Record per-second usage for clusters (dedicated and shared tiers).
This endpoint is called by the worker's hourly usage scraping job.

Per-second billing (like AWS/GCP/Azure):
- Minimum charge: 60 seconds (1 minute)
- Billed per second after the first minute

For each cluster, records a UsageRecord with the per-second cost based on:
- Provider (hetzner, gcp, aws, azure)
- Tier (shared, testing, production)

## Headers

- `x-service-token` string, required

## Request body

- ClusterUsageBatch: Batch of cluster usage records from the worker.
  - `records` ClusterUsageRecord[], required
    - `cluster_id` string, required
    - `period_start` string, required
    - `period_end` string, required
    - `seconds` integer, required
    - `cpu_millicores` integer, nullable
    - `memory_mi` integer, nullable
    - `node_count` integer, nullable
    - `cpu_requests_millicores` integer, nullable
    - `memory_requests_mi` integer, nullable
    - `inventory` ClusterInventory: Normalized cluster resources read from the Kubernetes API, priced by the per-provider catalog. Provider-agnostic.
      - `nodes` InventoryNode[]
        - `instance_type` string, required
        - `region` string, required
        - `zone` string, required
      - `load_balancer_count` integer
      - `volume_gb` number

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mengi/apis/mengi-cloud.md) · [All operations](https://skmtc.dev/mengi/apis/mengi-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/mengi/apis/mengi-cloud/revisions/4ae9b375cdbb?raw)