ExternalCreditBalanceResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/vaquill-ai/main/json-schema/vaquill-ai-external-credit-balance-response-schema.json",
  "title": "ExternalCreditBalanceResponse",
  "description": "Spendable credit balance for the calling API key's account.",
  "x-generated": "2026-10-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-india-openapi.yml#/components/schemas/ExternalCreditBalanceResponse",
  "properties": {
    "creditsRemaining": {
      "type": "number",
      "title": "Creditsremaining",
      "description": "Credits you can actually spend right now. Deliberately the same field name that metered responses return, so one name means one thing across the API.\n\nDerived from your live credit buckets under the same expiry rule the billing path applies, so it never promises credits a call would refuse to spend."
    },
    "usdRemaining": {
      "type": "number",
      "title": "Usdremaining",
      "description": "`creditsRemaining` in USD, at the published conversion rate (1 credit = $0.01). Provided so you do not have to hardcode the rate; `GET /api/v1/api-credits/pricing` is its source of truth."
    },
    "bySource": {
      "items": {
        "$ref": "#/$defs/CreditSourceBreakdown"
      },
      "type": "array",
      "title": "Bysource",
      "description": "`creditsRemaining` split by funding source, and it always sums to it. Worth reading because the sources do not behave alike: `subscription` credits are use-it-or-lose-it at the period end, while `payg` credits you bought are durable and burn last."
    },
    "nextExpiry": {
      "anyOf": [
        {
          "$ref": "#/$defs/CreditExpiry"
        },
        {
          "type": "null"
        }
      ],
      "description": "The soonest expiry across your credits, or `null` if none of them expire. Poll this to avoid silently forfeiting an allowance."
    },
    "plan": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Plan",
      "description": "Active API subscription tier, or `null` on pay-as-you-go. Also determines your rate-limit multiplier. Briefly cached, so a subscription change made seconds ago may not be reflected yet; `creditsRemaining` is always live."
    },
    "totalPurchased": {
      "type": "number",
      "title": "Totalpurchased",
      "description": "Lifetime credits added to this account."
    },
    "totalConsumed": {
      "type": "number",
      "title": "Totalconsumed",
      "description": "Lifetime credits spent by this account."
    },
    "rateLimit": {
      "anyOf": [
        {
          "$ref": "#/$defs/CreditRateLimit"
        },
        {
          "type": "null"
        }
      ],
      "description": "How fast this key may call, as opposed to how much it may spend. The two ceilings are independent: holding credits does not exempt you from these, and staying under these does not pay for a call.\n\nThese are the ceilings themselves, with your plan already applied, so you can size a client BEFORE issuing a request. The `X-RateLimit-*` headers on every response report the same ceilings plus your live headroom, and the two agree."
    },
    "asOf": {
      "type": "string",
      "format": "date-time",
      "title": "Asof",
      "description": "When this balance was computed. The value is live, not cached, so this is the instant the buckets were read."
    }
  },
  "type": "object",
  "required": [
    "creditsRemaining",
    "usdRemaining",
    "totalPurchased",
    "totalConsumed",
    "asOf"
  ],
  "$defs": {
    "CreditExpiry": {
      "properties": {
        "at": {
          "type": "string",
          "format": "date-time",
          "title": "At",
          "description": "UTC instant at which the next credits expire."
        },
        "credits": {
          "type": "number",
          "title": "Credits",
          "description": "Credits that expire at that instant. They stop being spendable immediately at `at`, not when the nightly sweep records it."
        }
      },
      "type": "object",
      "required": [
        "at",
        "credits"
      ],
      "title": "CreditExpiry",
      "description": "The soonest expiry, and what dies with it."
    },
    "CreditRateLimit": {
      "properties": {
        "perMinute": {
          "type": "integer",
          "title": "Perminute",
          "description": "Requests allowed per minute on this key, plan multiplier already applied."
        },
        "perHour": {
          "type": "integer",
          "title": "Perhour",
          "description": "Requests allowed per hour on this key."
        },
        "perDay": {
          "type": "integer",
          "title": "Perday",
          "description": "Requests allowed per day on this key."
        }
      },
      "type": "object",
      "required": [
        "perMinute",
        "perHour",
        "perDay"
      ],
      "title": "CreditRateLimit",
      "description": "Request-rate ceilings in force for the calling key.\n\nA SECOND, independent ceiling alongside credits, and the two are unrelated:\nyou can hold credits and still be throttled, or sit far under these limits\nand be refused for an empty balance."
    },
    "CreditSourceBreakdown": {
      "properties": {
        "source": {
          "type": "string",
          "title": "Source",
          "description": "Where the credits came from. `bonus` (signup grant), `subscription` (plan allowance, use-it-or-lose-it), `payg` (purchased packs) and `comp` (complimentary) exist today, and this list is not closed: read the values rather than matching on a fixed set."
        },
        "credits": {
          "type": "number",
          "title": "Credits",
          "description": "Credits remaining in this source. 1 credit = $0.01."
        }
      },
      "type": "object",
      "required": [
        "source",
        "credits"
      ],
      "title": "CreditSourceBreakdown",
      "description": "Live credits held under one funding source."
    }
  }
}