comecerodocs
Usage metrics

Create a metric

POST
/usage/metrics

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).

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Request Body

A metric.

application/json
  1. body
metric_id?string

Optional. Defaults to a new id.

name*string

Required.

event_key?string

The metric_key your app sends. 1 to 64 of a-z 0-9 _ . -, unique in the account and mode, and it never changes. Defaults to name, which fails for most names (for example "AI tokens"), so send it.

unit_label*string

Required.

aggregation*string

Required.

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

Up to 20 property names.

status?string

Defaults to active.

Value in"active""archived"
billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"

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 POST 'https://api.comecero.com/api/v1/usage/metrics' \  -H 'Content-Type: application/json' \  -d '{  "metric_id": "met_ai_tokens",  "name": "AI tokens",  "event_key": "ai_tokens",  "unit_label": "token",  "aggregation": "sum",  "allowed_properties": [    "model"  ]}'
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"}

List metrics GET

The account's metrics, by `metric_id`, up to 500. Secret and trusted tokens may call it; a limited token may not (`403`).

Get a metric GET

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