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

# Credits & pricing

> How Chariot meters usage in credits, when they're charged, and when they're refunded.

Usage on Chariot is metered in **credits**. Your workspace holds a credit balance; each request spends from it.

## What things cost

| Product               | Cost                             |
| --------------------- | -------------------------------- |
| Text to speech (`v0`) | **1 credit per input character** |

A 200-character TTS request costs 200 credits. The character count is taken from your input `text` (after trimming whitespace). Each response reports the exact charge:

* Synchronous `POST /v1/tts` → `Credit-Utilized` response header
* Streaming `POST /v1/tts/stream` → `Credit-Utilized` response header
* WebSocket → `credits_utilized` field on each `audio.done` message

## When credits are charged

<AccordionGroup>
  <Accordion title="Synchronous and HTTP streaming: up front">
    The full cost (character count × 1) is debited before generation begins. If the generation fails, the charge is refunded (see below).
  </Accordion>

  <Accordion title="WebSocket: per sentence">
    Credits are charged sentence by sentence, as each sentence finishes synthesizing, based on the characters actually spoken. A long session spreads its cost across many small debits rather than one up-front charge.
  </Accordion>
</AccordionGroup>

## Failed generations are refunded

You are not charged for audio you don't receive. If a generation fails after credits were debited, Chariot **refunds** them automatically:

* **Synchronous**, a failed `POST /v1/tts` refunds the full charge and returns a `500` error.
* **HTTP streaming**, if the stream fails partway, you keep whatever audio already streamed and the charge is **fully refunded**.
* **WebSocket**, billing is per sentence, so a mid-session failure only ever affects the current sentence; completed sentences stay billed.

<Note>
  Refunds are issued as a new credit grant, so your balance returns to its prior level. The original charge remains visible in your usage history for auditing.
</Note>

### WebSocket grace on the last sentence

On a WebSocket session, each sentence is streamed to you **before** its charge is applied. If your balance can't cover a sentence, that already-streamed sentence is delivered free of charge as a one-time grace, then the session closes with code `4402` (insufficient credits). No partially-paid or unpaid audio is withheld mid-sentence.

## Checking your balance

Call [`GET /v1/credits`](/api-reference/endpoint/user-credits):

```bash theme={null}
curl https://api.chariot.in/v1/credits \
  -H "chariotai-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "available_credits": 500000,
  "next_expiry_at": "2026-10-11T06:27:16.943000Z",
  "grants": [
    {
      "grant_id": "786a4ad5-95cc-4dd8-916d-022476f07b89",
      "source": "subscription_cycle",
      "amount_initial": 500000,
      "amount_remaining": 500000,
      "granted_at": "2026-07-13T06:27:18Z",
      "expires_at": "2026-10-11T06:27:16Z"
    }
  ]
}
```

| Field               | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `available_credits` | Total spendable credits across all active grants.         |
| `next_expiry_at`    | When the soonest-expiring grant lapses.                   |
| `grants`            | Per-grant breakdown, each with its own amount and expiry. |

## How credits are granted and expire

Credits arrive as **grants**, each with its own expiry:

* **Subscription cycle**, your plan grants credits at the start of each billing cycle. These expire at the end of the cycle, so unused cycle credits don't roll over indefinitely.
* **Adjustments**, credits added by Chariot (e.g. support adjustments or refunds).

When you spend, Chariot draws from the **soonest-to-expire grant first**, so credits are used before they lapse. A grant stops counting toward your balance the moment it expires, even if some amount remains.

<Warning>
  A `403 InsufficientCreditsException` means your workspace is out of credits:

  ```json theme={null}
  { "statusCode": 403, "error": "InsufficientCreditsException",
    "message": "Workspace has 4 credits; needs 128" }
  ```

  Top up or upgrade your plan from the dashboard to continue.
</Warning>