Metered usage

Some plans include an allowance of a metered resource, such as compute minutes, on top of the flat monthly price. The billing page shows what you have used against what is included.

How an allowance behaves

Usage accumulates over the billing period and resets when the period rolls over. Going past the included amount does not stop anything; what happens next depends on the meter:

• Billed overage: the extra is priced per unit and appears on the next invoice.
• Hard cap: the allowance is the limit and further usage is refused until the period resets or you upgrade.

The billing page says which applies to each meter, along with the price per unit where there is one.

Reporting usage from your own code

If you are metering something your application does, record it through the API:

curl -X POST https://your-app.example.com/api/v1/usage \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "meter": "compute_minutes",
    "quantity": 12,
    "idempotencyKey": "job-2026-09-07-a41f"
  }'

Always send an idempotencyKey. A retry with the same key is recorded once, which is what keeps a network failure from double-billing your own customers. Use something derived from the work itself, such as a job id, rather than a random value per attempt.

Reading current usage

curl https://your-app.example.com/api/v1/usage -H "x-api-key: $API_KEY"

You get each meter with its used amount, included amount, overage and whether the allowance is exhausted. That is the same data the billing page shows, so you can surface it in your own interface.

Where the numbers go

Usage is recorded here first, then forwarded to the payment provider if that provider bills metered overage. Not every provider does; where one does not, the numbers are still tracked and displayed, but the overage is not charged automatically.