# Understand billing and usage

> Follow available and reserved balance through estimate, reservation, settlement, release, and ledger records.

Canonical: https://entirefeed.com/docs/operate/billing-and-usage

EntireFeed uses prepaid usage billing. Estimation is free. Creating a paid generation reserves its current estimate from available balance while work is active.

## Read balance without changing it

`GET /v1/billing/summary` returns `available`, `reserved`, and `total` USD amounts. `GET /v1/billing/ledger` returns immutable balance movements and supports cursor, type, date, and generation filters.

Public API keys can only read billing data. Adding balance and managing payment methods remain signed-in Console actions.

## Reconcile each generation

Read `usage.billing_status` on the generation. `reserved` means the estimate is still held. `settled` means usage was charged. `released` means held balance returned to available balance. `manual_review` means automation must stop until the cost is resolved.

The ledger is the audit trail. A single generation can produce a reserve followed by settlement, release, or a bounded adjustment. When final cost exceeds the reservation, any extra debit is capped at the current available balance and cannot make that balance negative.

## Read available and reserved balance

### cURL

```bash
curl https://api.entirefeed.com/v1/billing/summary \
  -X GET \
  -H "Authorization: Bearer $ENTIREFEED_API_KEY"
```

### TypeScript

```typescript
const response = await fetch("https://api.entirefeed.com/v1/billing/summary", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.ENTIREFEED_API_KEY}`,
  },
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

### Python

```python
import os
import requests

response = requests.request(
    "GET",
    "https://api.entirefeed.com/v1/billing/summary",
    headers={"Authorization": f"Bearer {os.environ['ENTIREFEED_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

```json
{
  "available": {
    "amount_usd": "23.80"
  },
  "reserved": {
    "amount_usd": "1.20"
  },
  "total": {
    "amount_usd": "25.00"
  },
  "currency": "usd"
}
```

## Read the usage ledger

### cURL

```bash
curl https://api.entirefeed.com/v1/billing/ledger?generation_id=gen_0123456789abcdef0123456789abcdef \
  -X GET \
  -H "Authorization: Bearer $ENTIREFEED_API_KEY"
```

### TypeScript

```typescript
const response = await fetch("https://api.entirefeed.com/v1/billing/ledger?generation_id=gen_0123456789abcdef0123456789abcdef", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.ENTIREFEED_API_KEY}`,
  },
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

### Python

```python
import os
import requests

response = requests.request(
    "GET",
    "https://api.entirefeed.com/v1/billing/ledger?generation_id=gen_0123456789abcdef0123456789abcdef",
    headers={"Authorization": f"Bearer {os.environ['ENTIREFEED_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

```json
{
  "data": [
    {
      "id": "8e2dc660-4b75-4a51-9176-6d70fe0b2c08",
      "type": "RESERVE",
      "amount_usd": "-1.20",
      "available_after_usd": "23.80",
      "reserved_after_usd": "1.20",
      "generation_id": "gen_0123456789abcdef0123456789abcdef",
      "description": "Reserved estimated operation cost.",
      "created_at": "2026-07-12T08:30:00Z"
    }
  ],
  "next_cursor": null
}
```

## Interpret billing status

| Status | Meaning | Balance behavior |
| --- | --- | --- |
| `reserved` | The current estimate is held while work is active. | Included in reserved balance, not available balance. |
| `settled` | Final usage was charged. | The settled amount remains spent; unused hold can be released. |
| `released` | The held amount was returned. | Released funds are available again. |
| `manual_review` | Final cost could not be resolved automatically. | The hold remains unavailable until resolution. |

## Reconcile releases and bounded adjustments

| Scenario | Amounts | Result |
| --- | --- | --- |
| Final cost below reservation | $1.20 reserved; $0.90 final | Settle $0.90 and release $0.30 to available balance. |
| Overage covered | $1.20 reserved; $1.50 final; at least $0.30 available | Settle $1.20 and debit a $0.30 adjustment. |
| Overage capped | $1.20 reserved; $1.50 final; $0.20 available | Settle $1.20 and debit a $0.20 adjustment. Available balance stops at $0.00. |

Additional debit is capped at the current `available_balance` and cannot create a negative balance.