Billing Units

Last verified: 2026-05-03 (Task #334 — docs accuracy pass).

Every successful response includes a meta.billing_units value. That number is what the calling key is charged against for the call. It is recorded in api_usage_events.billing_units and never returned for calls that 4xx/5xx out before they reach the handler.

What counts toward requests

The requests quota dimension counts billable events only — that is, api_usage_events rows where billing_units > 0. This matters in two places:

1. GET /v1/usage logs billing_units = 0 and doesn't move the requests counter. You can poll your own usage as often as you want.
2. Pre-handler rate-limit rejections also log billing_units = 0. We still record the attempt for forensics, but over-limit attempts don't double-charge you for the limit you already hit.

Provider failures

502 provider_unavailable and 504 weather_refresh_timeout responses still bill the same units as a successful response would have — we already paid the upstream cost (or the timeout cost) and the cache layer counts a slot regardless. Validation failures (400) do not bill.

Watches

Watch creation bills 1 unit. After that, a daily background job accrues 1 unit per active watch per day as long as the watch's status='active' and the current time is inside [starts_at, ends_at]. A watch that is paused, expired, failed, or cancelled does not accrue new daily units.

How to see the cost of a call

Inspect meta.billing_units on the response, or query api_usage_events for a window of recent calls:

SELECT
  endpoint,
  SUM(billing_units) AS units,
  COUNT(*) AS calls
FROM api_usage_events
WHERE developer_account_id = $1
  AND created_at >= date_trunc('month', now() at time zone 'utc')
GROUP BY endpoint
ORDER BY units DESC;