# Usage meter API (/docs/usage-billing/usage-meter-api)

The usage meter is a separate service from the Comecero API, at `https://usage.comecero.com`. Call it from your server: it does not answer browsers. Your app calls one route on it, to send usage events. It does not take Comecero API tokens, only [usage keys](/docs/usage-billing/set-up#5-create-a-usage-key). For a walk-through, see [Send Usage](/docs/usage-billing/send-usage).

## Send usage events [#send-usage-events]

**POST** `https://usage.comecero.com/v1/events`

### Headers [#headers]

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer apk_live_...` or `Bearer apk_test_...` |
| `Content-Type` | `application/json` |

The key decides the account and the mode (live or test). Nothing in the body can change them.

### Body [#body]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | array | Yes | 1 to 1,000 events. The whole body is at most 1 MiB. |

Each event:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operation_id` | string | Yes | 1 to 128 of `A-Z a-z 0-9 _ . : -`. Unique per metric for 35 days. Resending it is safe. |
| `external_customer_id` | string | Yes | 1 to 128 of `A-Z a-z 0-9 _ . : -`. Your id for the customer, the `customer_id` of their billing agreement. No emails or card numbers. |
| `metric_key` | string | Yes | 1 to 64 of `a-z 0-9 _ . -`. A metric's `event_key`. |
| `quantity` | string or number | Yes | 0 or more, at most 12 digits before the point and 6 after. A number must print exactly (no exponent). |
| `timestamp` | string | No | ISO 8601 with a time zone. At most 30 days old and 5 minutes ahead. Defaults to now. Counted in its UTC hour. |
| `properties` | object | No | Up to 20, only the metric's `allowed_properties`. Values are strings (up to 256 characters), finite numbers or booleans. |

Card numbers (any bare run of 13 to 19 digits, see [the rules](/docs/usage-billing/send-usage#no-card-data-or-personal-data)), card track data, emails and IP addresses are refused in `operation_id`, `external_customer_id` and property values.

````json
{
  "events": [
    {
      "operation_id": "req_7Hk2p9",
      "external_customer_id": "cust_8412",
      "metric_key": "ai_tokens",
      "quantity": "1250",
      "timestamp": "2026-11-01T09:41:07Z",
      "properties": { "model": "large" }
    }
  ]
}
````

### Answer [#answer]

````json
{
  "counted": 1,
  "duplicate": 0,
  "conflict": 0,
  "rejected": 0,
  "retry": 0,
  "results": [
    { "index": 0, "operation_id": "req_7Hk2p9", "status": "counted" }
  ]
}
````

| Field | Type | Description |
| --- | --- | --- |
| `counted`, `duplicate`, `conflict`, `rejected`, `retry` | integer | How many events got each answer. |
| `results` | array | One answer per event, in the order sent. |
| `results[].index` | integer | The event's place in `events`, from 0. |
| `results[].operation_id` | string | The event's `operation_id`, when it was readable. |
| `results[].status` | string | `counted`, `duplicate`, `conflict`, `rejected` or `retry`. See [answers](/docs/usage-billing/send-usage#answers). |
| `results[].code` | string | For `rejected`: why. See [what is rejected and why](/docs/usage-billing/send-usage#what-is-rejected-and-why). |
| `results[].field` | string | For `rejected`: where, for example `properties.order_ref`. Never the value. |

### Status codes [#status-codes]

| Status | Meaning |
| --- | --- |
| `200` | Every event has a final answer: `counted`, `duplicate`, `conflict` or `rejected`. |
| `429` | Some events got `retry`, or the account sent over 5,000 events or 50 requests this second (`too_many_requests`, nothing counted). Resend the whole batch: counted events come back as `duplicate`. |
| `400` | The request can't be used: `{ "error": "<code>" }` with `empty_body`, `invalid_json`, `events_missing`, `events_empty`, or `too_many_events` (over 1,000). |
| `401` | No `Authorization` header (`{ "message": "Unauthorized" }`). |
| `403` | The usage key is unknown, revoked, for the other mode, not active yet, or in the wrong format (`{ "message": "Forbidden" }`). |
| `413` | `body_too_large`: the body is over 1 MiB. |
| `503` | `try_again`: a temporary problem. Resend the batch. |

### Rules [#rules]

- **Exactly once.** An event is identified by its metric and `operation_id`. The first one sent is counted. The same one again with the same `external_customer_id`, `quantity` and `timestamp` is a `duplicate`; with a different one it is a `conflict`, and the first one stays.
- **Counted right away.** An event that is `counted` is in the totals at once. Billing reads them when the period ends.
- **Late events are billed.** An event for an hour that is already billed is billed on the next invoice as a **Late usage** line, as long as it is at most 30 days old.
- **Any customer id is counted.** Only ids that are the `customer_id` of a billing agreement are billed.
- **No negatives.** Corrections are made in Comecero, not in the meter.
- **Unknown metrics are refused.** A metric must exist, be `active`, and have reached the meter (usually seconds after you create it).
