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

# Credit balance

> Free authenticated account read. balance and credits_balance report the current available balance, which can include pending request reservations. recent_deductions counts debit ledger entries in the preceding 24 hours, including reservations later refunded. No upstream requests. Responses are private and never cached.

Requires your SocialQuery API key. Costs **0 credits** and makes no upstream requests.

The `balance` and legacy `credits_balance` values match. `recent_deductions` counts debit entries in the preceding 24 hours, including reservations later refunded.


## OpenAPI

````yaml GET /credits/balance
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /credits/balance:
    get:
      tags:
        - meta
      summary: Read your credit balance
      description: >-
        Free authenticated account read. balance and credits_balance report the
        current available balance, which can include pending request
        reservations. recent_deductions counts debit ledger entries in the
        preceding 24 hours, including reservations later refunded. No upstream
        requests. Responses are private and never cached.
      operationId: meta_credits_balance
      parameters: []
      responses:
        '200':
          description: 'Private account data. Cache-Control: private, no-store.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  platform:
                    type: string
                    const: meta
                  endpoint:
                    type: string
                    const: /v1/credits/balance
                  data:
                    type: object
                    properties:
                      balance:
                        type: integer
                      recent_deductions:
                        type: integer
                      credits_balance:
                        type: integer
                        description: Backward-compatible alias for balance.
                      user_id:
                        type: string
                        format: uuid
                    required:
                      - balance
                      - recent_deductions
                      - credits_balance
                      - user_id
                  credits_used:
                    type: integer
                    const: 0
                  credits_remaining:
                    type: integer
                  request_id:
                    type: string
                  cached:
                    type: boolean
                    const: false
                required:
                  - success
                  - platform
                  - endpoint
                  - data
                  - credits_used
                  - credits_remaining
                  - request_id
                  - cached
        '401':
          description: Missing, invalid, expired or revoked key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialQueryError'
        '403':
          description: The key does not grant this endpoint scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialQueryError'
        '405':
          description: Use GET.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialQueryError'
        '422':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialQueryError'
        '429':
          description: API key rate limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialQueryError'
        '503':
          description: Account storage temporarily unavailable. No credit charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialQueryError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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