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.

View as Markdown

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 MCP tool returns, so asking Claude “how many credits do I have left” reads the same data.

Usage summary

GET /api/usage/summary/

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

{
  "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).

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

Each entry:

{
  "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 is credited.

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