Usage

Read your usage

GET /meta/usage reports your team's charges, grouped by day, service, meter, mode, key, and rate version. Use it to reconcile charges with your own records or break down a bill by key. Usage reports are free.

Select a UTC month with month, in the format YYYY-MM. You can read the current month and the 24 completed months before it. Usage updates as you use Motor. Once Motor creates an invoice for a month, that month's usage is final.

curl 'https://api.motor.dev/meta/usage?month=2026-10&service_id=feature_flags' \
  -H 'Authorization: Bearer <MOTOR_SECRET_KEY>'

Narrow the report with service_id, meter_id, mode, or key_id. Each page has up to limit rows (1 to 200, 50 by default), ordered by day. When next_cursor isn't null, use it as the cursor parameter to read the next page. Keep the month and filters the same.

Rows, units, and amounts

Each row has these fields:

{
  "day": "2026-10-05",
  "service_id": "feature_flags",
  "meter_id": "feature_flags.evaluations",
  "mode": "live",
  "key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs",
  "rate_version": null,
  "unit": "evaluation requests",
  "quantity": 412000,
  "unit_price_usd": "0.00003",
  "amount_usd": "12.36"
}

A service can have multiple meters. Each meter has separate rows, even when the prices are the same. For example, feature flag evaluation requests and metric events each cost $0.03 per 1,000, but appear in separate rows. Rows are also grouped by mode and rate_version, which identifies the published rates used to calculate the charge. rate_version is null for services without versioned rates.

quantity is the number of units used, measured in the row's unit. unit_price_usd and amount_usd are exact amounts in US dollars, returned as decimal strings with up to twelve decimal places. This preserves sub-cent amounts. Motor rounds each invoice line to the nearest cent, so the total in the usage report can differ from the invoice total by less than a cent per invoice line.

The report summarizes charges. Motor's automatic retries are included in the original charge. Submitting a new request incurs a separate charge.

Access and errors

Authenticate with a secret key. Publishable keys and client tokens can't read usage. Your secret key can read usage across all keys on your team, but only for services it has permission to use. A key with access to all services can read all of your team's usage.

Errors use the standard {"error": {"code": ..., "message": ...}} format. A missing or invalid key returns 401 unauthorized; a suspended team returns 403 account_suspended. service_id for a service the key cannot access returns 403 forbidden. key_id for an unknown key or a key outside your team returns 404 not_found. A missing or malformed month, a month outside the supported range, an invalid limit, or a cursor from a different month or set of filters returns 422 invalid_field.