Ingest usage event

POST

/v1/usage-events

curl --request POST \
  --url http://localhost:8080/v1/usage-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "external_customer_id": "example", "event_name": "example", "quantity": 1, "dimensions": {}, "idempotency_key": "example", "timestamp": "2026-04-15T12:00:00Z" }'

• Local development

Authorizations

• BearerAuth

Request Body^required

Media typeapplication/json

object

external_customer_id

required

The customer’s external_id (your identifier), not the internal hc_cus_ id.

string

event_name

required

The meter’s event_name (e.g. “tokens”).

string

quantity

required

One of:

number

number

string

string

dimensions

Scalar labels of the event (e.g. {“model”, “token_type”}). A price takes an event whose labels include the price’s dimension_match.

object

key

additional properties

any

idempotency_key

required

Your unique ID for this event. Pick it once, before the first send, and send the same key on every retry of the event. Keys are unique per tenant and mode (live or test), forever. An event whose key was already used is not stored again: the first event wins and the new body is discarded. So never reuse a key for a different event, such as a batch index or a timestamp that can repeat, or that usage is lost. Empty or whitespace-only keys are refused with 422, and so are keys longer than 255 characters. This is the only dedup key: the usage routes ignore the Idempotency-Key header.

string

<= 255 characters

timestamp

string format: date-time

Example ^generated

{
  "external_customer_id": "example",
  "event_name": "example",
  "quantity": 1,
  "dimensions": {},
  "idempotency_key": "example",
  "timestamp": "2026-04-15T12:00:00Z"
}

Responses

200

Idempotency replay — the original event is returned unchanged with an Idempotent-Replayed: true header. No duplicate row is written. The new body is not compared with the original.

Media typeapplication/json

object

id

required

string

tenant_id

string

customer_id

required

string

meter_id

required

string

quantity

required

Exact quantity as a decimal string (e.g. “1.5”).

string

dimensions

The dimension values sent with the event. Absent when none were sent.

object

key

additional properties

any

idempotency_key

string

timestamp

required

string format: date-time

origin

How the event arrived. backfill means POST /v1/usage-events/backfill.

string

Allowed values: api backfill

provider_cost_cents

What serving this event cost you at your provider, in US cents as a decimal string (e.g. “0.45”), set when the event arrived: from your provider cost rates, or the cost the sender reported (see provider_cost_source). Absent when the cost is unknown or the event has no costed dimensions.

string

provider_cost_source

Where provider_cost_cents came from: table (your provider cost rates), observed (the cost the sender reported), or not_applicable (the meter has no costed dimensions). Absent when the cost is unknown.

string

Allowed values: table not_applicable observed

billing_status

What Hardcount found when the event arrived. It checked the event against the customer’s subscriptions, the plans and prices in force, and the invoices already built at that moment. Sent only on the answer that wrote the event; the event is stored all the same.

A status that is present was true at that moment:

• after_close: the event’s time is already invoiced. A spend-threshold invoice counts only once it is paid. Bill the event with a one-off invoice if it should be charged.
• not_on_plan: a billing period not invoiced yet holds the event’s time, but its plan has no price for this meter.
• outside_subscription: no active or trialing subscription of the customer bills the event’s time. For example, it has none, or the time is before one starts, in a free trial, or after one ends or its scheduled cancel.
• no_price: the plan that bills the event’s time prices this meter, but no price of that plan takes the event’s dimensions. A price takes an event whose dimensions include all of its dimension_match, compared as strings: the number 1 is not the string "1".

No billing_status means Hardcount found no reason then. It is not a promise that the event will be billed. Hardcount checks only the customer’s current billing periods: time after a period end whose invoice is not built yet is not checked, nor is time after a trial’s end before Hardcount ends the trial. A later change can change the outcome either way: a subscription created, activated or changed, a trial extended, a scheduled cancel undone, or a price added. The invoice is the final answer.

Two cases can make a present status wrong: a price change whose save began before a billing period started and finished after the request read the prices, and a subscription change saved while the request is in flight. Absent on a replay and on a read.

string

Allowed values: after_close no_price not_on_plan outside_subscription

Example

{
  "origin": "api",
  "provider_cost_source": "table",
  "billing_status": "after_close"
}

201

Event ingested. A billing_status is what Hardcount found when the event arrived (see UsageBillingStatus); the event is stored all the same.

Media typeapplication/json

object

id

required

string

tenant_id

string

customer_id

required

string

meter_id

required

string

quantity

required

Exact quantity as a decimal string (e.g. “1.5”).

string

dimensions

The dimension values sent with the event. Absent when none were sent.

object

key

additional properties

any

idempotency_key

string

timestamp

required

string format: date-time

origin

How the event arrived. backfill means POST /v1/usage-events/backfill.

string

Allowed values: api backfill

provider_cost_cents

What serving this event cost you at your provider, in US cents as a decimal string (e.g. “0.45”), set when the event arrived: from your provider cost rates, or the cost the sender reported (see provider_cost_source). Absent when the cost is unknown or the event has no costed dimensions.

string

provider_cost_source

Where provider_cost_cents came from: table (your provider cost rates), observed (the cost the sender reported), or not_applicable (the meter has no costed dimensions). Absent when the cost is unknown.

string

Allowed values: table not_applicable observed

billing_status

What Hardcount found when the event arrived. It checked the event against the customer’s subscriptions, the plans and prices in force, and the invoices already built at that moment. Sent only on the answer that wrote the event; the event is stored all the same.

A status that is present was true at that moment:

• after_close: the event’s time is already invoiced. A spend-threshold invoice counts only once it is paid. Bill the event with a one-off invoice if it should be charged.
• not_on_plan: a billing period not invoiced yet holds the event’s time, but its plan has no price for this meter.
• outside_subscription: no active or trialing subscription of the customer bills the event’s time. For example, it has none, or the time is before one starts, in a free trial, or after one ends or its scheduled cancel.
• no_price: the plan that bills the event’s time prices this meter, but no price of that plan takes the event’s dimensions. A price takes an event whose dimensions include all of its dimension_match, compared as strings: the number 1 is not the string "1".

No billing_status means Hardcount found no reason then. It is not a promise that the event will be billed. Hardcount checks only the customer’s current billing periods: time after a period end whose invoice is not built yet is not checked, nor is time after a trial’s end before Hardcount ends the trial. A later change can change the outcome either way: a subscription created, activated or changed, a trial extended, a scheduled cancel undone, or a price added. The invoice is the final answer.

Two cases can make a present status wrong: a price change whose save began before a billing period started and finished after the request read the prices, and a subscription change saved while the request is in flight. Absent on a replay and on a read.

string

Allowed values: after_close no_price not_on_plan outside_subscription

Example

{
  "origin": "api",
  "provider_cost_source": "table",
  "billing_status": "after_close"
}

422

Validation failed and nothing was stored. param names the field: idempotency_key when it is missing, blank or longer than 255 characters, quantity when it is missing or not as described above, external_customer_id or event_name for an unknown customer or meter, timestamp for a malformed one, and properties when it has a key (it was renamed dimensions; null or {} is ignored).

503

ingest_unavailable: a customer or meter lookup, or the read of the customer’s billing periods, could not be answered. Nothing was recorded; retry.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}