> ## Documentation Index > Fetch the complete documentation index at: https://vaquill.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get your credit balance > 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" } ``` ## OpenAPI ````yaml https://api.vaquill.ai/external/openapi.json get /api/v1/credits/balance openapi: 3.1.0 info: title: Vaquill Developer API description: >- Public API for legal statutes and legislation. **Authentication**: Pass your API key via the `Authorization: Bearer vq_key_...` header. **Credits**: Each call costs API credits. See `GET /api/v1/api-credits/pricing` for the full pricing matrix. ## Jurisdictions | Jurisdiction | Coverage | `countryCode` | |---|---|---| | **United States** | USC and the Statutes at Large, the CFR and its annual editions, all 52 state and territory statutory codes (50 states plus DC and Puerto Rico), state administrative regulations, court rules, federal and state constitutions, federal agency guidance and adjudications, the Federal Register, the Sentencing Guidelines and US tax treaties. | `US` | See the full [Coverage page](https://www.vaquill.ai/docs/api-guide/coverage) for the jurisdiction-by-jurisdiction breakdown, or call `/us/statutes/coverage` for live counts. Coverage is per (jurisdiction, corpusType) pair, so treat that endpoint as the authoritative list rather than this summary. ## Endpoints - **US Statutes**: Search and retrieve any of the corpora above with full text, resolve a citation to its exact section, browse the statutory hierarchy, read a section as it stood on a past date, and follow its change history, cross-references and defined terms - **Board Watches**: Subscribe to a corpus source and get a webhook or email when it refreshes with real changes (free, API key required) - **Pricing**: Credit costs per endpoint (no auth required) ## Rate limits Limits are enforced per API key and scale with your plan. A `429` response includes a `Retry-After` header. | Plan | Per minute | Per hour | Per day | |---|---|---|---| | Vaquill API Pro | 60 | 1,000 | 2,000 | | Vaquill API Business | 150 | 2,500 | 10,000 | For full documentation, visit the [API Reference](https://www.vaquill.ai/docs/api-reference/). 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 servers: - url: https://api.vaquill.ai description: Production security: - ApiKeyAuth: [] tags: - name: US Statutes description: >- Search and retrieve US primary law. Covers the United States Code and the Statutes at Large, the Code of Federal Regulations and its annual editions, state statutory codes and administrative regulations, federal and state constitutions, court rules, Federal Register rules and Presidential documents, federal and state agency guidance, agency adjudications, state Attorney General opinions, the Sentencing Guidelines and US tax treaties. Scope a search with the `corpusType` filter, and call `/us/statutes/coverage` for the live jurisdiction-by-corpusType list. - **Search**: Search across all USC, CFR, state, and regulatory sections - **Section**: Get metadata, citation, hierarchy, and source links for a specific section - **Body**: Get the full text of a section - name: Board Watches description: >- Law-change alerts. Subscribe to a **board** (a tracked corpus source, identified by `corpusType` plus an optional `state`) and get a webhook or email whenever it refreshes with real changes, naming the exact sections that changed. Fetch old-vs-new text for any amended section via the change diff. Boards refresh on their own existing cadence; watching one does not change how often it refreshes. Every endpoint here is **free**: authenticated by API key and rate-limited, but not credit-metered. See the [Law Change Alerts guide](https://www.vaquill.ai/docs/api-guide/alerts) for the full walkthrough. - name: Pricing description: >- Credit pricing and conversion rates. No authentication required. 1 credit = $0.01 USD. - 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. externalDocs: description: Full API Reference url: https://www.vaquill.ai/docs/api-reference/ 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 usdRemaining: 1030.39 bySource: - source: comp credits: 20000 - source: payg credits: 64699 - source: subscription credits: 18340 nextExpiry: at: '2026-10-12T13:56:31Z' credits: 18340 plan: business totalPurchased: 143960 totalConsumed: 48471 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. 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. 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 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 totalConsumed: type: number title: Totalconsumed description: Lifetime credits spent by this account. examples: - 46961 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. 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. 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 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. 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. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: vq_key_* description: >- API key issued from the developer dashboard. Pass as `Authorization: Bearer vq_key_...` ````