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

# Billing & Rate Limits

> Credit-based billing, usage tracking, and rate limits.

The Abigail API uses a **credit-based billing system**. You purchase credits, and
usage is deducted in real-time based on token consumption. LLM usage is never blocked --
only document exports are credit-gated.

## How billing works

1. Purchase a credit package (or receive \$25 welcome credits on signup)
2. Every API call that uses AI consumes tokens (input + output)
3. Token costs are deducted from your credit balance automatically
4. Every response includes balance headers so you can track spending

## Token pricing

| Service Type    | Rate                   |
| --------------- | ---------------------- |
| Standard Input  | \$50.00 per 1M tokens  |
| Standard Output | \$200.00 per 1M tokens |

A typical `/analyze` call processes \~2,000 input tokens and \~1,500 output tokens,
costing approximately \$0.40 per analysis.

### Model multiplier

Your account has a model version setting (default 1.0x) that multiplies base token
prices. Higher-capability models may have higher multipliers.

## Credit packages

| Package      | Price   | Credits | Bonus  |
| ------------ | ------- | ------- | ------ |
| Starter      | \$25    | \$25    | --     |
| Professional | \$100   | \$100   | +\$10  |
| Business     | \$500   | \$500   | +\$75  |
| Enterprise   | \$2,000 | \$2,000 | +\$400 |

Custom amounts are also supported (1:1 credits, no bonus).

New accounts receive **\$25 in welcome credits** to get started.

## Document export pricing

Document exports (DOCX downloads) are **credit-gated** -- the API returns HTTP 402
if your balance is insufficient.

| Document Type | Price   |
| ------------- | ------- |
| OA Response   | \$49.00 |
| IDS           | \$9.00  |
| Form          | \$5.00  |
| Drawing       | \$5.00  |

<Warning>
  Document exports are the only operations that block on insufficient credits.
  All LLM-based operations (analyze, examiner lookup) always complete regardless
  of balance.
</Warning>

## What is free?

These operations are never billed:

* `GET /v1/openclaw/lookup/{app_number}` -- application metadata
* `GET /v1/openclaw/deadlines/{app_number}` -- response deadlines
* `GET /v1/openclaw/draft-roa/status/{job_id}` -- polling draft status
* `GET /v1/openclaw/download/{job_id}` -- downloading a completed DOCX (the draft
  submission is billed, not the download)

## Usage tracking headers

Every response from authenticated endpoints includes these headers:

```
X-Credit-Balance: 142.50
X-Balance-Status: healthy
X-Usage-Requests-Today: 23
X-Usage-Requests-Hour: 5
```

### Balance status thresholds

| Status     | Balance    | Meaning                          |
| ---------- | ---------- | -------------------------------- |
| `healthy`  | > \$25     | Normal operation                 |
| `low`      | $10 -- $25 | Consider purchasing more credits |
| `very_low` | $5 -- $10  | Running low                      |
| `critical` | \< \$5     | Nearly depleted                  |

When balance is `low` or below, responses also include:

```
X-Purchase-Prompt: true
X-Purchase-Message: Your credit balance is low. Purchase more credits to continue using AI features.
```

## Handling 402 responses

When a document export is blocked for insufficient credits:

```json theme={null}
{
  "error": true,
  "error_code": "insufficient_credits",
  "message": "Insufficient credits for OA Response export ($49.00 required).",
  "agent_suggestion": "The user needs to purchase more credits before exporting this document. Current balance is insufficient."
}
```

Your agent should inform the user to purchase credits and retry.

## Rate limits

| Tier                    | Rate                | Burst              |
| ----------------------- | ------------------- | ------------------ |
| Free endpoints          | 60 requests/minute  | 10 requests/second |
| API key (authenticated) | 120 requests/minute | 20 requests/second |

Rate limits are per API key (authenticated) or per IP (free endpoints).

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1708732800
```

### Handling 429 responses

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

def call_with_retry(url, headers, json_body, max_retries=3):
    for attempt in range(max_retries):
        resp = httpx.post(url, headers=headers, json=json_body)
        if resp.status_code == 429:
            wait = 2 ** attempt  # 1, 2, 4 seconds
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit exceeded after retries")
```