UsageMeter

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/frase-io/json-schema/frase-io-usage-meter-schema.json",
  "title": "UsageMeter",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/frase-io-usage-api-openapi.yml#/components/schemas/UsageMeter",
  "type": "object",
  "properties": {
    "used": {
      "type": "integer"
    },
    "limit": {
      "type": [
        "integer",
        "null"
      ],
      "description": "null when the plan grants unlimited use of this pool."
    },
    "remaining": {
      "type": [
        "integer",
        "null"
      ],
      "description": "null when unlimited. Never negative - an over-consumed pool reports 0 rather than a negative number a client might read as headroom."
    },
    "unlimited": {
      "type": "boolean"
    },
    "resets_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When this pool refills, or null when there is nothing honest to announce. Null covers three real cases: the reset threshold has passed and the clearing job has not caught up, the subscription status makes the org ineligible for a reset run, and a never-converted trial whose one-time pool never rolls. Treat null as 'unknown', not 'never'."
    },
    "bonus_credits": {
      "type": "integer",
      "description": "Bonus credits already folded into limit. Present only on pools that have them (today: articles, and only when the org holds a balance), absent everywhere else. This is what reconciles remaining with limit - used, which for articles are deliberately different numbers: bonus credits are spent BEFORE the monthly allowance and do not expire with the cycle, so an org past its monthly limit that holds bonus credits genuinely has that many articles left. Recompute the same answer as max(0, (limit - bonus_credits) - used) + bonus_credits."
    }
  }
}