跳到主要内容
Docs/Features/Usage Metering

Usage Metering

Real-time per-tenant metering of every billable resource (crawl tasks, leads, contacts, AI tokens, seats). Surfaces a usage dashboard, drives in-app upgrade prompts, and enforces hard limits at the gateway.

![Usage Metering](/docs-img/usage-metering.png)

What It Does

  • Counts usage of 5 metered resources in real time.
  • Compares against your plan's quota and exposes a percentage.
  • Shows a 12-month history per metric.
  • Triggers a hard 429 at 100% on hard-limit metrics; soft-limit metrics keep going and bill on overage.

    • When to Use

    Surface this dashboard to your finance / ops lead so nobody is surprised by an overage bill.

    Reading Usage

    curl https://api.anvilhk.com/api/v1/me/usage \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "X-Tenant-ID: $TENANT"

    Returns each metric with used and limit.

    Hard vs Soft Limits

    MetricTypeBehaviour at 100%
    Crawl tasksHard429 on next request
    LeadsSoftBill on overage, pre-set rate
    ContactsSoftBill on overage
    AI tokensHard429
    SeatsHardCannot invite

    API Endpoints

  • `GET /api/v1/me/usage` — current snapshot.
  • `GET /api/v1/me/usage/history?metric=ai_tokens&months=12` — historical.

    • Pricing & Limits

    Quotas are plan-keyed. Overage rates are tenant-specific — see your invoice or **Settings > Billing > Overage**.

    Gotchas

  • Usage updates are eventually consistent — the dashboard can lag the gateway counter by up to 5 seconds at peak.
  • Soft-limit overage is invoiced at month-end; you can't pre-pay overage.
  • Cancelling mid-month does NOT pro-rate overage; it's calculated against the current period.
    • ← Back to Docs