# Usage & credits

> The usage summary endpoint — plan, balance, in-flight jobs, 30-day history — and the credit ledger with its entry types. Also backs the get_usage MCP tool.

Two read-only endpoints answer "where do my credits stand" and "where did they go": a current-period summary and an append-only ledger. The summary is also what the [`get_usage`](https://figgshield.ai/documentation/mcp.md) MCP tool returns, so asking Claude _"how many credits do I have left"_ reads the same data.

## Usage summary

`GET /api/usage/summary/`

```bash
curl https://api.figgshield.ai/api/usage/summary/ \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"
```

```json
{
  "plan": {
    "slug": "pro",
    "name": "Pro",
    "monthly_credits": 1100,
    "parallel_limit": 5,
    "price_monthly_cents": 2900
  },
  "credits": {
    "balance": 812,
    "used_this_period": 288,
    "granted_this_period": 1100,
    "rollover": 0,
    "period_start": "2026-07-01T00:00:00Z",
    "period_end": "2026-08-01T00:00:00Z"
  },
  "jobs": { "in_flight": 1, "parallel_limit": 5 },
  "history": [
    { "date": "2026-07-01", "credits_used": 78, "generations": 4 }
  ],
  "by_model": [
    { "model": "Kling", "credits": 210, "count": 6 },
    { "model": "Nano Banana 2", "credits": 64, "count": 8 }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `plan` | Your current plan. `null` if the account has no active subscription (in that state the balance is 0 and creating generations returns `402 subscription_required`). |
| `credits.balance` | Spendable credits right now, including rollover and top-ups. |
| `credits.used_this_period` / `granted_this_period` | Burn and grant totals for the current monthly credit period. |
| `credits.rollover` | Credits carried over from earlier periods. |
| `credits.period_start` / `period_end` | Bounds of the current monthly credit period. |
| `jobs` | In-flight generations versus your plan's parallel limit — useful for avoiding `409 parallel_limit_reached`. |
| `history` | Last 30 days of `credits_used` and `generations` per day. |
| `by_model` | Credit and generation totals per model (Kling, Nano Banana 2) for the current period. |

A cheap pre-flight pattern: read `credits.balance` and `jobs.in_flight` before submitting a batch, then submit up to `parallel_limit - in_flight` jobs whose combined cost fits the balance.

## Credit ledger

`GET /api/ledger/` — every credit movement on your account, newest first, read-only, in the standard list envelope (`?page=N` to page).

```bash
curl "https://api.figgshield.ai/api/ledger/?page=1" \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"
```

Each entry:

```json
{
  "uuid": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "entry_type": "burn",
  "amount": -35,
  "balance_after": 812,
  "description": "Kling generation 0b8f6a2e",
  "created_at": "2026-07-06T09:00:00Z"
}
```

### Entry types

| `entry_type` | Direction | When it happens |
| --- | --- | --- |
| `grant` | + | Monthly plan credits land at the start of a credit period. |
| `burn` | − | A generation is charged. |
| `refund` | + | A failed generation returns its charge automatically. |
| `rollover` | + | Unused credits carried into a new period. |
| `expiry` | − | Rolled-over credits age out, or the subscription lapses. |
| `topup` | + | A manual or automatic [top-up](https://figgshield.ai/documentation/billing.md) is credited. |

`amount` is signed; `balance_after` is the running balance, so the ledger reconciles exactly against `credits.balance` in the summary.