Vaquill AI Credits API

openapi: 3.2.0
info:
  title: Vaquill Ai Credits API
  version: 1.0.0
  contact:
    name: Vaquill API Support
    url: https://www.vaquill.ai
    email: support@vaquill.ai
  license:
    name: Proprietary
    url: https://www.vaquill.ai/terms
  termsOfService: https://www.vaquill.ai/terms
  description: 'Operations tagged Credits across 2 of this provider''s published API definitions: vaquill-ai-openapi.json, vaquill-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.vaquill.ai
  description: Production
security:
- ApiKeyAuth: []
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Credits
  description: 'Your own credit balance: what is spendable right now, where it came from, and what is about to expire.


    Free and never charged, so it is safe to poll for low-balance alerting or to pre-flight a batch job.'
paths:
  /api/v1/credits/balance:
    get:
      tags:
      - Credits
      summary: Get your credit balance
      description: 'Returns the credits this API key''s account can spend right now.


        **Free.** This endpoint is never charged, so you can poll it to drive alerting

        or a pre-flight check without the check itself costing you anything. It is rate

        limited like every other key-authenticated route.


        **Authentication:** any valid `vq_key_` key. No particular scope is required.


        ## What the number means


        `creditsRemaining` is derived from your live credit buckets under the same

        expiry rule the billing path applies, so it is what a call would actually be

        allowed to spend, not a cached figure that a nightly job later corrects.


        It is the same field name metered responses use, so you can read `creditsRemaining`

        the same way everywhere.


        ## Not all credits behave alike


        Read `bySource` before assuming a balance is durable. `subscription` credits are

        use-it-or-lose-it and are forfeited at the end of the period, while `payg`

        credits you purchased burn last and persist. `nextExpiry` tells you what is

        about to be forfeited and when, which is the one thing a balance alone cannot.


        ## Two separate ceilings


        Credits are how MUCH you may spend; `rateLimit` is how FAST you may call. They

        are independent, so a healthy balance does not exempt you from throttling and

        staying under the rate limit does not pay for a call.


        `rateLimit` has your plan applied and lets you size a client before issuing a

        request. Every response also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`

        and `X-RateLimit-Reset` for the per-minute window, plus `X-RateLimit-Limit-Day`

        and `X-RateLimit-Remaining-Day` for the daily backstop; those report the same

        ceilings with your live headroom.


        ## Example


        ```bash

        curl https://api.vaquill.ai/api/v1/credits/balance \

        -H "Authorization: Bearer $VAQUILL_API_KEY"

        ```


        ```json

        {

        "creditsRemaining": 103039.0,

        "usdRemaining": 1030.39,

        "bySource": [

        { "source": "payg", "credits": 102539.0 },

        { "source": "subscription", "credits": 500.0 }

        ],

        "nextExpiry": { "at": "2026-10-01T00:00:00Z", "credits": 500.0 },

        "plan": "business",

        "totalPurchased": 150000.0,

        "totalConsumed": 46961.0,

        "asOf": "2026-09-19T12:34:56Z"

        }

        ```'
      operationId: get_credit_balance_api_v1_credits_balance_get
      responses:
        '200':
          description: Current spendable balance for the calling key's account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCreditBalanceResponse'
              example:
                creditsRemaining: 103039.0
                usdRemaining: 1030.39
                bySource:
                - source: comp
                  credits: 20000.0
                - source: payg
                  credits: 64699.0
                - source: subscription
                  credits: 18340.0
                nextExpiry:
                  at: '2026-10-12T13:56:31Z'
                  credits: 18340.0
                plan: business
                totalPurchased: 143960.0
                totalConsumed: 48471.0
                rateLimit:
                  perMinute: 150
                  perHour: 2500
                  perDay: 10000
                asOf: '2026-09-19T12:34:56Z'
        '401':
          description: Missing, malformed or unrecognised API key. Note this endpoint accepts ONLY a `vq_key_` API key; a dashboard session token is rejected here.
          content:
            application/json:
              example:
                detail: Invalid token
        '429':
          description: Request-rate ceiling exceeded. Retry after the `Retry-After` header. Being throttled says nothing about your balance.
          content:
            application/json:
              example:
                detail: Rate limit exceeded. Try again in 42 seconds.
    servers:
    - url: https://api.vaquill.ai
      description: Production
components:
  schemas:
    CreditRateLimit:
      properties:
        perMinute:
          type: integer
          title: Perminute
          description: Requests allowed per minute on this key, plan multiplier already applied.
          examples:
          - 150
        perHour:
          type: integer
          title: Perhour
          description: Requests allowed per hour on this key.
          examples:
          - 2000
        perDay:
          type: integer
          title: Perday
          description: Requests allowed per day on this key.
          examples:
          - 10000
      type: object
      required:
      - perMinute
      - perHour
      - perDay
      title: CreditRateLimit
      description: 'Request-rate ceilings in force for the calling key.


        A SECOND, independent ceiling alongside credits, and the two are unrelated:

        you can hold credits and still be throttled, or sit far under these limits

        and 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.'
          examples:
          - payg
        credits:
          type: number
          title: Credits
          description: Credits remaining in this source. 1 credit = $0.01.
          examples:
          - 1030.43
      type: object
      required:
      - source
      - credits
      title: CreditSourceBreakdown
      description: Live credits held under one funding source.
    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.


            Derived 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.'
          examples:
          - 103039.0
        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.'
          examples:
          - 1030.39
        bySource:
          items:
            $ref: '#/components/schemas/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: '#/components/schemas/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.
          examples:
          - business
        totalPurchased:
          type: number
          title: Totalpurchased
          description: Lifetime credits added to this account.
          examples:
          - 150000.0
        totalConsumed:
          type: number
          title: Totalconsumed
          description: Lifetime credits spent by this account.
          examples:
          - 46961.0
        rateLimit:
          anyOf:
          - $ref: '#/components/schemas/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.


            These 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
      title: ExternalCreditBalanceResponse
      description: Spendable credit balance for the calling API key's account.
    CreditExpiry:
      properties:
        at:
          type: string
          format: date-time
          title: At
          description: UTC instant at which the next credits expire.
          examples:
          - '2026-10-01T00:00:00Z'
        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.
          examples:
          - 500.0
      type: object
      required:
      - at
      - credits
      title: CreditExpiry
      description: The soonest expiry, and what dies with it.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vq_key_*
      description: 'API key issued from the developer dashboard. Pass as `Authorization: Bearer vq_key_...` (preferred).'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'The same API key as a bare header value: `X-API-Key: vq_key_...`. Equivalent to the Bearer form.'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: 'The same API key as a query parameter: `?api_key=vq_key_...`. Use only where you cannot set a header. A URL can end up in proxy and server logs, browser history and shared links, so prefer either header form, and rotate a key that has leaked.'
externalDocs:
  description: Full API Reference
  url: https://www.vaquill.ai/docs/api-reference/
x-refined-from:
- vaquill-ai-openapi.json
- vaquill-ai-openapi.yml