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

# Credits

> Cuadra AI uses credits to bill for AI usage. Monitor balance, purchase additional credits, and optimize consumption.

## Credit Pools

| Pool             | Source                  | Behavior                  |
| ---------------- | ----------------------- | ------------------------- |
| **Subscription** | Monthly plan allocation | Resets on billing date    |
| **Purchased**    | One-time purchases      | Never expires, rolls over |

**Consumption order:** Subscription credits first, then purchased credits.

***

## Check Balance

### Dashboard

View credits at [dashboard.cuadra.ai](https://dashboard.cuadra.ai) → **Billing**.

### API

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.cuadra.ai/v1/usage \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://api.cuadra.ai/v1/usage",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  usage = response.json()
  print(f"Credits: {usage['credits']['available']} available")
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/usage', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const usage = await response.json();
  console.log(`Credits: ${usage.credits.available} available`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "credits": {
    "used": 15000,
    "limit": 50000,
    "available": 35000,
    "purchasedBalance": 100000,
    "totalAvailable": 135000,
    "billingPeriod": "monthly",
    "periodStart": "2025-01-01T00:00:00Z",
    "periodEnd": "2025-01-31T23:59:59Z"
  },
  "storage": { "used": 524288000, "limit": 1073741824 },
  "plan": { "tier": "pro", "name": "Professional" }
}
```

***

## Purchase Credits

Dashboard → **Billing** → **Purchase Credits**.

Credit packages are available for Pro and Enterprise plans. See the Dashboard for current pricing.

<Info>
  Purchased credits never expire. Use them anytime.
</Info>

***

## When Credits Run Out

API returns HTTP 402 Payment Required:

```json theme={null}
{
  "title": "Insufficient Credits",
  "status": 402,
  "detail": "Insufficient credits. Required: 75 credits. Available: 50 credits."
}
```

| Recovery Option | Action                             |
| --------------- | ---------------------------------- |
| Wait            | Subscription resets monthly        |
| Purchase        | Buy credits instantly              |
| Upgrade         | Higher tier = more monthly credits |

***

## Monitor Usage

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.cuadra.ai/v1/usage?period=month" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://api.cuadra.ai/v1/usage",
      params={"period": "month"},
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  print(response.json())
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.cuadra.ai/v1/usage?period=month', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  console.log(await response.json());
  ```
</CodeGroup>

***

## Reduce Costs

| Strategy                            | Impact                   |
| ----------------------------------- | ------------------------ |
| Use smaller models for simple tasks | Significant savings      |
| Set `maxTokens` limit               | Caps response length     |
| Keep system prompts concise         | Fewer input tokens       |
| Cache frequent responses            | Avoid duplicate requests |

***

## FAQ

### How are credits calculated?

Credits are based on token usage. The exact formula depends on the model and request type. Each Chat API response includes token counts in the `usage` field.

### Do unused subscription credits roll over?

No. Subscription credits reset on your billing date. Purchased credits roll over indefinitely.

### Can I get a refund for unused credits?

Purchased credits are non-refundable. Contact [support@cuadra.ai](mailto:support@cuadra.ai) for billing questions.

### How do I set up low-balance alerts?

Dashboard → **Settings** → **Notifications**. Set thresholds for email alerts.

***

## Related

<CardGroup cols="2">
  <Card title="Pricing" icon="tag" href="https://cuadra.ai/pricing">
    Plans and tiers
  </Card>

  <Card title="Usage API" icon="chart-bar" href="/api-reference/usage">
    Query usage data
  </Card>
</CardGroup>