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

# Billing

> Estimates, holds, charges, balance and usage.

## Estimate

`POST /estimate` takes the same body as `POST /jobs` and returns what submitting it now would hold. It charges nothing and creates no job.

```bash theme={null}
curl https://api.blon.ai/v1/estimate \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"A ceramic teapot on a linen table, soft morning light"}}'
```

```json theme={null}
{
  "model": "gpt-image-2",
  "cost": {
    "currency": "CREDITS",
    "amount": "8"
  },
  "kind": "exact",
  "reason": null
}
```

`kind` is `exact` when the price is known from the inputs, or `upper_bound` when part of it depends on the output; `reason` then explains the bound. A `{url}` input is imported first, because the price can depend on its duration.

## Holds and charges

1. **Submit.** Blon holds the estimate from your balance. A balance that cannot cover it fails with `402 insufficient_credits`.
2. **Finish.** A completed job is charged from its measured usage (the job's `usage`). What is left of the hold is released.
3. **Fail or cancel.** The hold is released and `charged` is `"0"`.

The job's `cost` shows this:

| Field | Meaning |
| - | - |
| `currency` | `USD` for a `blon_api_` key, `CREDITS` otherwise |
| `estimated` | The estimate held at submission. It does not change |
| `charged` | What was charged; `null` until the job is terminal |
| `refunded` | Money returned after a charge |

A released hold is not a refund and does not appear in `refunded`. A job is always charged at the price in effect when it was submitted.

## Balance

```bash theme={null}
curl https://api.blon.ai/v1/balance \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "currency": "USD",
  "available": "18.425",
  "held": "0.0042",
  "usage_this_month": "1.5708",
  "spend_limit": {
    "amount": "50.00",
    "spent": "1.5708",
    "window": "month",
    "resets_at": "2026-11-01T00:00:00.000Z"
  }
}
```

| Field | Meaning |
| - | - |
| `available` | What you can spend now |
| `held` | Held for jobs that are not finished |
| `usage_this_month` | Spent this calendar month |
| `spend_limit` | Only when the key has a spend limit: `amount`, `spent`, `window` (`day`, `week`, `month` or `lifetime`) and `resets_at` |

Over the spend limit, submissions fail with `403 api_key_spend_limit_exceeded`.

## Usage

```bash theme={null}
curl "https://api.blon.ai/v1/usage?timeframe=day" \
  -H "Authorization: Bearer $BLON_API_KEY"
```

```json theme={null}
{
  "currency": "USD",
  "timeframe": "day",
  "start": "2026-10-24T00:00:00.000Z",
  "end": "2026-10-31T00:00:00.000Z",
  "data": [
    {
      "bucket_start": "2026-10-30T00:00:00Z",
      "model": "gpt-image-2",
      "api_key_id": "key_7d2f9a",
      "jobs": 12,
      "units": {
        "output_images": 12
      },
      "cost": "0.48"
    }
  ]
}
```

| Parameter | Meaning |
| - | - |
| `timeframe` | `hour`, `day`, `week` or `month`. Default `day` |
| `start` | RFC 3339. Default 7 days before `end` |
| `end` | RFC 3339. Default now. At most 31 days after `start` |

Only settled jobs are counted, bucketed by settlement time. `cost` is charged net of refunds. Usage is a report, not an invoice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.