comecerodocs
Usage metrics

Get a metric

GET
/usage/metrics/{metric_id}

One metric. Secret and trusted tokens may call it; a limited token may not (403).

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

metric_id*string

The metric id.

Response Body

Success.

application/json
  1. response

One thing you count and bill for. See https://docs.comecero.com/docs/usage-billing/metrics-and-aggregations

object?string

Always metric.

metric_id?string

Your id, or met_ plus 32 characters.

name?string

Shown on invoice lines.

event_key?string

The metric_key usage events use. 1 to 64 of a-z 0-9 _ . -. Unique in the account and mode. Never changes.

unit_label?string

For example token. Shown on invoice lines.

aggregation?string

sum adds up quantities. gauge keeps the highest reading of each hour and bills the highest hour.

Value in"sum""gauge"
allowed_properties?array<string>

Up to 20 property names (1 to 64 of A-Z a-z 0-9 _) events may carry.

status?string

The usage meter refuses events for archived metrics.

Value in"active""archived"
version?integer

Goes up on every change.

synced_version?integer

The version the usage meter has.

aggregation_locked?boolean

true once the usage meter has the metric. aggregation can't change after that.

billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"
test?boolean

Test or live.

account_id?string

The account.

date_created?string

When it was created.

Formatdate-time
date_modified?string

When it last changed.

Formatdate-time
Example Request
curl -X GET 'https://api.comecero.com/api/v1/usage/metrics/string'
Example Response
{  "object": "metric",  "metric_id": "met_ai_tokens",  "name": "AI tokens",  "event_key": "ai_tokens",  "unit_label": "token",  "aggregation": "sum",  "allowed_properties": [    "model"  ],  "status": "active",  "version": 1,  "synced_version": 1,  "aggregation_locked": true,  "billing_region": "us",  "test": false,  "account_id": "AB1234",  "date_created": "2026-11-01T09:00:00Z",  "date_modified": "2026-11-01T09:00:00Z"}

Create a metric POST

Creates one thing you count. Call it from your server with a secret token. Secret and trusted tokens may call it; a limited token may not (`403`).

Create or replace a metric PUT

Saves the whole definition: fields you leave out are cleared (`allowed_properties` becomes empty, `status` becomes `active`). `event_key` never changes, and `aggregation` can not change once the usage meter has the metric (`409`). It answers `201` when it creates the metric: then send `name` and `unit_label` too. Secret and trusted tokens may call it; a limited token may not (`403`).