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

# Get credit balance

> Read your organization's current credit balance and billing cycle. Lets you observe your balance programmatically — including from async-only workloads — without making a sync /v1/monitor/* request just to inspect the X-Credits-Remaining header. The authoritative check is enforced when each task is charged.

## Overview

Read your organization's current credit balance and billing cycle. Use it to:

* **Read your balance programmatically**: Get remaining credits without opening the dashboard
* **Support async-only workloads**: Observe your balance without making a billable sync `/v1/monitor/*` request just to read the `X-Credits-Remaining` header
* **Drive low-balance alerts**: Notify your team before you run out
* **Gate submissions**: Pause task submission when the balance is too low to cover the next batch

## Response fields

| Field           | Type            | Description                                                                                                      |
| --------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `remaining`     | integer         | Credits currently remaining for your organization                                                                |
| `perCycle`      | integer \| null | Credits granted per billing cycle. `null` for free-tier organizations with no active subscription                |
| `cycleResetsAt` | string \| null  | ISO 8601 timestamp for when the current billing cycle ends and credits reset. `null` for free-tier organizations |

## Example usage

### Read your current balance

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

  ```json Response theme={null}
  {
    "remaining": 48210,
    "perCycle": 1562500,
    "cycleResetsAt": "2026-08-10T17:35:27.000Z"
  }
  ```
</CodeGroup>

### Low-balance alerts and a submission breaker

If you run an async-only workload, poll `GET /v1/credits` to alert on a low balance and to stop submitting before you run out — no need to make a billable sync request just to read your balance:

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from 'axios';

  const API_KEY = process.env.API_KEY;
  const CREDITS_URL = 'https://api.cloro.dev/v1/credits';
  const COST_PER_BATCH = 5000;

  async function getCredits() {
    const { data } = await axios.get(CREDITS_URL, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    return data;
  }

  const { remaining, cycleResetsAt } = await getCredits();

  if (remaining < 10_000) {
    const resetInfo = cycleResetsAt ? `resets ${cycleResetsAt}` : 'no active billing cycle';
    console.warn(`Low credit balance: ${remaining} remaining (${resetInfo})`);
  }

  if (remaining < COST_PER_BATCH) {
    console.log('Insufficient credits — pausing submission until the cycle resets or you top up');
  } else {
    await submitNextBatch();
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  API_KEY = os.environ['API_KEY']
  CREDITS_URL = 'https://api.cloro.dev/v1/credits'
  COST_PER_BATCH = 5000

  def get_credits():
      response = requests.get(
          CREDITS_URL,
          headers={'Authorization': f'Bearer {API_KEY}'}
      )
      response.raise_for_status()
      return response.json()

  credits = get_credits()
  remaining = credits['remaining']
  cycle_resets_at = credits['cycleResetsAt']

  if remaining < 10_000:
      reset_info = f'resets {cycle_resets_at}' if cycle_resets_at else 'no active billing cycle'
      print(f'Low credit balance: {remaining} remaining ({reset_info})')

  if remaining < COST_PER_BATCH:
      print('Insufficient credits — pausing submission until the cycle resets or you top up')
  else:
      submit_next_batch()
  ```
</CodeGroup>

<Note>
  Every task is checked against your live balance when it's charged, so this read is a guardrail rather than a ledger. To attribute exact cost per task, use the `creditsCharged` field on the [task status](/docs/api-reference/endpoint/get-task-status) response instead.
</Note>


## OpenAPI

````yaml api-reference/openapi.json GET /v1/credits
openapi: 3.1.0
info:
  title: cloro
  description: API for monitoring AI responses across different providers and regions
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.cloro.dev
    description: Production server
security:
  - bearerAuth: []
paths:
  /v1/credits:
    get:
      summary: Get credit balance
      description: >-
        Read your organization's current credit balance and billing cycle. Lets
        you observe your balance programmatically — including from async-only
        workloads — without making a sync /v1/monitor/* request just to inspect
        the X-Credits-Remaining header. The authoritative check is enforced when
        each task is charged.
      operationId: getCredits
      responses:
        '200':
          description: Current credit balance and billing cycle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
        '401':
          description: Unauthorized - Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    CreditsResponse:
      type: object
      required:
        - remaining
        - perCycle
        - cycleResetsAt
      properties:
        remaining:
          type: integer
          description: Credits currently remaining for your organization.
          example: 48210
        perCycle:
          type: integer
          nullable: true
          description: >-
            Credits granted per billing cycle. Null for free-tier organizations
            with no active subscription.
          example: 1562500
        cycleResetsAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the current billing cycle ends and credits reset. Null for
            free-tier organizations with no active subscription.
          example: '2026-08-10T17:35:27.000Z'
    AuthenticationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - MISSING_API_KEY
                - INVALID_API_KEY_FORMAT
                - INVALID_OR_EXPIRED_API_KEY
              example: MISSING_API_KEY
            message:
              type: string
              example: Missing or invalid API key
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    InternalError:
      type: object
      oneOf:
        - properties:
            success:
              type: boolean
              example: false
            error:
              type: string
              example: Maximum retries exceeded
        - properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  example: INTERNAL_SERVER_ERROR
                message:
                  type: string
                  example: Internal server error
                timestamp:
                  type: string
                  format: date-time
                  example: '2025-01-15T12:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````