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

# Get Credit Balance

> Check your remaining credit balance

Check how many credits you have left, along with your lifetime purchased and used totals. It's worth a quick call before kicking off anything that reserves credits — like [character extraction](/api-reference/extract/static-bin) or a [render](/api-reference/render/create).

## Response

```json theme={null}
{
  "balance": 250.0,
  "credits": 250.0,
  "total_purchased": 500.0,
  "total_used": 250.0,
  "updated_at": "2026-06-12T08:00:00Z"
}
```

| Field             | Description                                     |
| ----------------- | ----------------------------------------------- |
| `balance`         | Credits available to spend right now.           |
| `credits`         | Alias of `balance` (spec-compliant field name). |
| `total_purchased` | Lifetime credits added to the account.          |
| `total_used`      | Lifetime credits consumed.                      |
| `updated_at`      | When the balance was last updated.              |

<Note>
  Insufficient balance causes credit-consuming endpoints to fail with a `402` error. See [Pricing](/pricing) for what each operation costs.
</Note>

## Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://apis.viggle.ai/api/credits"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
  }

  response = requests.get(url, headers=headers)
  response.raise_for_status()
  result = response.json()

  print(f"Credit balance: {result['balance']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/api/credits", {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  });

  const result = await response.json();

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(`Credit balance: ${result.balance}`);
  ```

  ```bash cURL theme={null}
  curl -X GET https://apis.viggle.ai/api/credits \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>


## OpenAPI

````yaml GET /api/credits
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security: []
paths:
  /api/credits:
    get:
      tags:
        - Credits
      summary: Get Credit Balance
      description: Retrieve the current credit balance for the authenticated user.
      operationId: getCreditBalance
      responses:
        '200':
          description: Credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
components:
  schemas:
    CreditBalance:
      type: object
      properties:
        balance:
          type: number
          example: 250
          description: Current credit balance
        credits:
          type: number
          example: 250
          description: Alias of balance (spec-compliant field name)
        total_purchased:
          type: number
          example: 500
          description: Total credits purchased
        total_used:
          type: number
          example: 250
          description: Total credits used
        updated_at:
          type: string
          format: date-time
          description: Timestamp of last balance update
    Error:
      type: object
      description: >-
        Simple error. `detail` is a human-readable message (used for auth
        errors).
      properties:
        detail:
          type: string
          example: 'API key required. Use Authorization: Bearer sk-xxx'
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Invalid or missing API key. Pass it as Authorization: Bearer
              sk-...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````