> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit balance

> Credits you can spend now, credits your running tasks hold, and when your plan's credits renew.

Reading it costs nothing, so a program can check it before each batch. `remaining` already excludes the credits your queued and running tasks hold. What each field means is on [Credits and limits](/concepts/credits-and-limits.md#check-your-balance).


## OpenAPI

````yaml GET /v1/credits
openapi: 3.1.0
info:
  title: querying.ai
  description: >-
    One API for every AI answer engine. Every task is asynchronous: submit, then
    collect the result via webhook or polling.
  version: 1.0.0
servers:
  - url: https://api.querying.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/credits:
    get:
      tags:
        - Operations
      summary: Get credit balance
      description: >-
        Your account's credits: what you can spend now, what your queued and
        running tasks hold, what your plan grants each cycle and when the cycle
        ends, and your top-up credits. Reading it costs nothing, so a program
        can check it before each batch.
      operationId: getCredits
      responses:
        '200':
          description: Your account's credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalance'
              example:
                success: true
                remaining: 1879939
                perCycle: 1000000
                cycleResetsAt: '2026-11-14T07:37:57.000Z'
                reserved: 61
                plan: max
                topUpBalance:
                  credits: 1000000
                  nextExpiresAt: '2027-01-19T10:01:57.000Z'
                  nextCredits: 1000000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            The key belongs to a sub-account. A sub-account spends its parent
            account's credits and has no balance; the parent account reads its
            usage at GET /v1/sub-accounts/{id}/usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: SUB_ACCOUNT_FORBIDDEN
                  message: >-
                    A sub-account spends its parent account's credits. The
                    parent account reads its usage at
                    /v1/sub-accounts/{id}/usage
                  timestamp: '2026-10-20T00:00:00.000Z'
components:
  schemas:
    CreditBalance:
      type: object
      required:
        - success
        - remaining
        - perCycle
        - cycleResetsAt
        - reserved
        - plan
        - topUpBalance
      properties:
        success:
          type: boolean
          const: true
        remaining:
          type: number
          description: >-
            Credits you can spend now, with up to two decimals. Tasks you
            already submitted hold their price in `reserved`, so it is not in
            this number. A submit that needs more returns `402
            INSUFFICIENT_CREDITS`.
        perCycle:
          type:
            - number
            - 'null'
          description: >-
            Credits your plan grants each billing cycle. `null` without an
            active plan.
        cycleResetsAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the current billing cycle ends. At renewal your balance becomes
            the next cycle's plan credits plus the top-up credits you still
            hold. `null` without an active plan.
        reserved:
          type: number
          description: >-
            Credits your queued and running tasks hold. A completed task is
            charged from its hold, and a failed task's hold returns to
            `remaining`.
        plan:
          type: string
          enum:
            - free
            - basic
            - pro
            - scale
            - max
          description: Your plan. `free` when no paid plan is active.
        topUpBalance:
          type:
            - object
            - 'null'
          description: >-
            Top-up credits within `remaining`. They last three months from
            purchase, carry over renewals, and are spent after your plan's
            credits. `null` when you have none.
          required:
            - credits
            - nextExpiresAt
            - nextCredits
          properties:
            credits:
              type: number
              description: Top-up credits left.
            nextExpiresAt:
              type: string
              format: date-time
              description: When the next of them expire.
            nextCredits:
              type: number
              description: How many expire then.
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable, safe to branch on. See the Errors guide for the full list.
        message:
          type: string
          description: For humans. May change.
        details:
          description: >-
            Context for the error. An array of `{field, message}` on most
            `VALIDATION_ERROR`s; an object elsewhere (for example `{id}` on
            `RESOURCE_NOT_FOUND`, `retryAfterSec` on 429 and 503 codes). Omitted
            when there is nothing to add.
          oneOf:
            - type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
            - type: object
              additionalProperties: true
        timestamp:
          type: string
          format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: MISSING_API_KEY
              message: Missing or invalid API key
              timestamp: '2026-07-09T04:12:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer <key>`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.