Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

List usage events

GET

/v1/usage-events

const url = 'http://localhost:8080/v1/usage-events?limit=50&offset=0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:8080/v1/usage-events?limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

Authorizations

BearerAuth

Parameters

Query Parameters

customer_id

string

meter_id

string

dimensions

string

Comma-separated key=value pairs matched against the event’s dimensions via JSONB containment (multiple pairs AND). Values that parse as JSON booleans/numbers are matched typed (“cached=true”, “attempt=2”); everything else as a string. Malformed pairs → 422. Example: model=gpt-4o,token_type=input.

from

string

Only events at or after this time. RFC 3339, or a date (YYYY-MM-DD) meaning 00:00:00 UTC.

string

Only events before this time, exclusive. RFC 3339, or a date (YYYY-MM-DD) meaning 23:59:59.999999 UTC that day, so the day is included.

limit

integer

default: 50 >= 1 <= 100

Rows per page, from 1 to 100. Default 50. Any other value, or one that is not a whole number, is a 422 with param: limit.

offset

integer

Rows to skip, 0 or more. Default 0. A negative value, or one that is not a whole number, is a 422 with param: offset.

Responses

200

Event list

application/json

object

data

required

Array<object>

object

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

total

required

How many rows match the request’s filters, on every page, not only this one. The audit log and the customer list’s search and name or email sort say where they stop counting.

integer

Example

{
  "data": [
    {
      "origin": "api",
      "provider_cost_source": "table",
      "billing_status": "after_close"
    }
  ]
}

422

validation_error: a malformed dimensions pair, a from or to that cannot be parsed, to before from, or a limit or offset out of range (param names the field).

application/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"
  }
}