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

# Billing & Usage

> Understand how thinnestAI billing works — token-based pricing, free tier credits, model-specific rates, and usage tracking.

# Billing & Usage

thinnestAI uses a simple, transparent billing system based on **USD tokens**. You add funds to your account, and usage is deducted as you go. No surprise invoices, no complex tiers — just pay for what you use.

## How Billing Works

1. **Add funds** to your account balance (in USD).
2. **Use your agents** — each chat message, voice call, and knowledge ingestion consumes tokens.
3. **Tokens are deducted** from your balance in real time.
4. **Top up** when your balance runs low, or enable auto-topup.

Your current balance and usage history are always visible in the dashboard under **Settings > Billing**.

## Free Tier and Trial Credits

Every new account receives **free trial credits** to get started:

| What You Get  | Amount                                                  |
| ------------- | ------------------------------------------------------- |
| Trial credits | Enough for \~100 chat messages or \~10 minutes of voice |
| Duration      | No expiry on trial credits                              |
| Limitations   | Some advanced features require a paid balance           |

Trial credits let you build, test, and deploy your first agent without entering payment information.

## Token Pricing

Usage is metered across three categories:

### Chat (Text Conversations)

Chat billing is based on the number of input and output tokens processed by the language model.

| Component           | Rate                        |
| ------------------- | --------------------------- |
| Input tokens        | Varies by model (see below) |
| Output tokens       | Varies by model (see below) |
| Knowledge retrieval | Small per-query fee         |

### Voice Calls

Voice is billed per minute of active call time.

| Component           | Rate                                                               |
| ------------------- | ------------------------------------------------------------------ |
| Voice call          | Per-minute rate (see [Phone Billing](/docs/billing/phone-billing)) |
| Phone number rental | Monthly fee per number                                             |

### Knowledge Ingestion

Uploading documents to your agent's knowledge base incurs a one-time ingestion fee.

| Component            | Rate                      |
| -------------------- | ------------------------- |
| Document ingestion   | Per-page or per-chunk fee |
| Embedding generation | Included in ingestion     |
| Storage              | Included                  |

## Topping Up Your Balance

### From the Dashboard

1. Go to **Settings > Billing**.
2. Click **Add Funds**.
3. Enter the amount (minimum \$5).
4. Complete payment via credit card or supported payment method.
5. Funds are available immediately.

### Auto-Topup

Never run out of credits unexpectedly. Enable auto-topup to automatically add funds when your balance drops below a threshold:

1. Go to **Settings > Billing > Auto-Topup**.
2. Toggle **Enable Auto-Topup**.
3. Set the **trigger threshold** (e.g., \$5.00).
4. Set the **topup amount** (e.g., \$25.00).
5. Save.

When your balance drops below $5.00, $25.00 is automatically charged to your payment method.

### Via the API

```bash theme={null}
curl -X POST https://api.thinnest.ai/billing/v3/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "payment_method_id": "pm_abc123"
  }'
```

## Viewing Usage

### Usage Dashboard

The billing dashboard shows:

* **Current balance**: Your available funds.
* **Usage this month**: Total spend broken down by category.
* **Usage by agent**: Which agents are consuming the most tokens.
* **Usage by model**: Cost breakdown per model.
* **Daily trend**: A chart of daily spending over the past 30 days.

### Usage API

```bash theme={null}
curl https://api.thinnest.ai/billing/v3/balance?period=month \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "period": "2026-03",
  "total_spent": 47.82,
  "balance": 152.18,
  "breakdown": {
    "chat": 32.15,
    "voice": 12.40,
    "knowledge": 3.27
  },
  "by_agent": [
    {"agent": "Customer Support", "spent": 28.50},
    {"agent": "Sales Assistant", "spent": 12.05},
    {"agent": "Research Bot", "spent": 7.27}
  ]
}
```

### Billing Records

Every charge is recorded with full details:

```bash theme={null}
curl https://api.thinnest.ai/billing/history/{user_id}?limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "records": [
    {
      "id": "bill_abc123",
      "type": "chat",
      "agent": "Customer Support",
      "model": "gpt-4o-mini",
      "input_tokens": 1250,
      "output_tokens": 340,
      "cost": 0.0004,
      "timestamp": "2026-03-05T10:30:00Z"
    }
  ]
}
```

## Spending Alerts

Set up alerts to stay on top of your spending:

1. Go to **Settings > Billing > Alerts**.
2. Add a spending threshold (e.g., "Alert me when daily spend exceeds \$10").
3. Choose notification method (email or dashboard notification).

## What Happens When Your Balance Runs Out

| Scenario            | Behavior                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| Balance reaches \$0 | Chat requests return an error; voice calls are not placed               |
| Auto-topup enabled  | Balance is automatically replenished                                    |
| Phone numbers       | Enter a grace period (see [Phone Billing](/docs/billing/phone-billing)) |
| Scheduled campaigns | Paused until balance is restored                                        |

Your agents, configuration, and data are never deleted due to low balance. Only active usage is paused.

## Next Steps

* [Phone & Voice Billing](/docs/billing/phone-billing) — Detailed voice and phone number pricing.
* [Deployment](/docs/deployment) — Self-host to manage your own costs.
* [Agents](/docs/agents) — Optimize your agents for cost efficiency.