Metering

Record each unit of work against the person or team that caused it, then turn usage into limits, credits and margins. This matters most for products that pay for every model call.

Recording usage

Terminal

curl -X POST https://api.dianthan.com/v1/usage/events \
  -H "X-API-Key: dn_live_…" -H "X-App-Id: app_…" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "ai.summary",
    "quantity": 1,
    "user_id": "usr_x81…",
    "metadata": { "document": "rec_9a…" }
  }'

metric is any name you choose: lowercase letters, digits and _ . : -, starting with a letter.
quantity defaults to 1 and can be any non-negative number, such as a count of tokens or seconds.
Attach usage to an organization with organization_id.

Record usage after the work succeeds. A failed request shouldn't cost your customer anything.

Reading usage

Terminal

curl "https://api.dianthan.com/v1/usage?user_id=usr_x81…&since=2026-11-01" \
  -H "X-API-Key: dn_live_…" -H "X-App-Id: app_…"

JSON

{
  "app_id": "app_…",
  "items": [
    { "metric": "ai.summary", "total": 212, "events": 212 },
    { "metric": "ai.tokens.output", "total": 381904, "events": 212 }
  ]
}

GET /v1/usage/:metric narrows to one metric. Organization totals are at GET /v1/organizations/:id/usage.

Limits from plans

In preview. Plans will carry quotas as entitlements, for example "ai.summaries.per_month": 500. Ask before running expensive work:

GET /v1/usage/ai.summary/remaining returns { "limit": 500, "used": 212, "remaining": 288, "resets_at": "…" }, and recording past the limit returns 402 quota_exceeded with the same body.

Credits

In preview. A prepaid balance per user or organization, kept in an append-only ledger. Credits come from plans (monthly allowances), top-ups (POST /v1/credits/top-up opens checkout), and grants. They're spent by usage events that carry a price. Each entry records why the balance changed, so a customer's statement adds up.

Model cost pass-through

In preview. Send the model and token counts with a usage event:
JSON
{ "metric": "ai.summary", "model": "claude-sonnet-5-5", "input_tokens": 1830, "output_tokens": 412 }
Dianthan prices the call at the provider's current rates, applies your markup (say, 3×), and deducts credits. Your dashboard shows revenue against model spend for each customer and each plan, so an unprofitable account stands out before the invoice arrives.

Patterns

Count requests, not attempts. Wrap the model call and record usage in the success branch only.
Use several metrics. Record ai.summary (one per request) and ai.tokens.output (tokens). One is what you sell; the other is what you pay.
Name metrics by feature. ai.summary and ai.chat let you price features differently later, which a single ai.calls metric wouldn't.