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

# Credits & Billing

> How a21e's credit system works, including managed and BYOK modes.

## Credit model

a21e uses a simple credit system: **1 credit = 1 enhancement** (one prompt compilation and execution).

Your balance is split into two buckets:

| Type             | Source                     | Behavior                    |
| ---------------- | -------------------------- | --------------------------- |
| **Subscription** | Monthly plan               | Resets on your renewal date |
| **Add-on**       | Credit packs, admin grants | Never expires, never resets |

Credits are consumed subscription-first. Add-on credits are only used once subscription credits are exhausted.

## Checking your balance

```bash theme={null}
curl https://api.a21e.com/v1/credits/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "balance": 550,
  "plan": "pro",
  "mode": "managed"
}
```

The `balance` field is your total available credits (subscription + add-on). `mode` indicates whether you're on **managed** (a21e-hosted LLM) or **BYOK** (your own provider key).

## Managed vs. BYOK

|                 | Managed                  | BYOK                         |
| --------------- | ------------------------ | ---------------------------- |
| **Credit cost** | 1 credit per enhancement | 1 credit per enhancement     |
| **LLM cost**    | Included in credit       | Billed by your provider      |
| **Setup**       | Nothing extra            | Add provider key in settings |

Credits are always required — they cover prompt engineering, context assembly, and orchestration. In BYOK mode, your provider handles the LLM inference cost separately.

See [BYOK guide](/guides/byok) for setup instructions.

## Usage tracking

### Summary

Get a high-level overview of your usage over a time period:

```bash theme={null}
curl "https://api.a21e.com/v1/usage/summary?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Daily breakdown

```bash theme={null}
curl "https://api.a21e.com/v1/usage/by-day?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Run history

List individual runs with pagination:

```bash theme={null}
curl "https://api.a21e.com/v1/usage/runs?days=30&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Each run includes the prompt title, credits used, model, provider, status, and duration.

### CSV export

Export your run history as a CSV file for accounting or analysis:

```bash theme={null}
curl "https://api.a21e.com/v1/usage/runs/export?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o runs.csv
```

## Credit ledger

The ledger provides a full audit trail of every credit transaction.

### List transactions

```bash theme={null}
curl "https://api.a21e.com/v1/credits/ledger?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Each entry includes a `entry_type` field:

| Entry type   | Meaning                                      |
| ------------ | -------------------------------------------- |
| `debit`      | Credit consumed by an enhancement            |
| `refund`     | Credits returned (e.g. failed execution)     |
| `grant`      | Credits added by admin or credit pack        |
| `pinned_hit` | Prompt pinning cache hit (no credit charged) |
| `dedup_hit`  | Deduplication cache hit (no credit charged)  |

### Period summary

Get aggregated credit activity over a time window (up to 90 days):

```bash theme={null}
curl "https://api.a21e.com/v1/credits/ledger/summary?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "total_debits": 142,
  "total_refunds": 3,
  "total_grants": 0,
  "cache_hits": 28,
  "net_change": -139,
  "period_days": 30,
  "since": "2026-02-06T00:00:00.000Z"
}
```

## Insufficient credits

When your balance reaches zero, API requests return a `402` error:

```json theme={null}
{
  "error": "INSUFFICIENT_CREDITS",
  "message": "Your credit balance is 0. Purchase additional credits or upgrade your plan.",
  "balance": 0
}
```

This applies to both managed and BYOK modes — credits are always required for prompt engineering.

## Organization credits

Organizations have a separate credit pool shared across all members:

* Org admins can purchase credits and set per-member spending limits
* Member usage is tracked individually within the org pool
* When a member's personal credits are exhausted, org credits are used (if allowed by policy)

See [Organizations](/account/organizations) for more on team billing.