Credits and usage API

These endpoints read your organization’s usage credit balance, start a prepaid top-up, and report AI and streaming usage. Authentication, error shapes and rate limits are covered in the REST API overview.

Prepaid AI credit and usage reporting. Amounts are in micro-credits (1,000,000 = $1.00). See Usage Credits and Billing for how balances work.

Create Credit Top-Up

Start a Stripe Checkout to buy prepaid AI credit. Pass exactly one of bundle_key (a preset bundle from the balance response) or amount_usd (a custom whole-dollar amount within the server-advertised bounds). The credit is applied to your balance when the checkout completes.

POST /api/v1/credits/topup

Auth: Bearer token required. Admin role.

Request body:

*Provide exactly one of the two.

Response:

{
  "url": "https://checkout.stripe.com/..."
}

Redirect the user to url to complete payment.

Errors:

• 400 — Neither or both fields provided, non-integer amount, or amount out of bounds.
• 503 — Billing is not available.

Get Credit Balance

GET /api/v1/credits/balance

Auth: Bearer token required.

Response:

{
  "allowance_micro": 750000,
  "prepaid_micro": 5000000,
  "plan_allowance_micro": 1000000,
  "plan_period_end": "2026-08-01T00:00:00",
  "low_balance": false,
  "bundles": [
    { "bundle_key": "bundle_10", "amount_micro": 10000000 }
  ],
  "custom_min_micro": 5000000,
  "custom_max_micro": 500000000
}

• allowance_micro — remaining monthly plan allowance.
• prepaid_micro — remaining purchased credit.
• plan_period_end — when the allowance refills (null on the Free plan).
• low_balance — server-computed flag for showing a low-balance warning.
• bundles, custom_min_micro, custom_max_micro — valid top-up options for Create Credit Top-Up.

Get Credit Ledger

Paginated history of credit movements: usage deductions, top-ups, and allowance refills (most recent first).

GET /api/v1/credits/ledger

Auth: Bearer token required.

Query parameters:

Response:

{
  "total": 132,
  "entries": [
    {
      "id": 990,
      "created_at": "2026-07-01T12:00:00",
      "entry_type": "usage_deduction",
      "balance_bucket": "allowance",
      "amount_micro": -42000,
      "model": "claude-4-sonnet",
      "test_run_id": 512,
      "is_streaming": false
    }
  ]
}

entry_type is one of usage_deduction, prepaid_topup, subscription_refill, and similar; balance_bucket is allowance or prepaid. amount_micro is signed (deductions are negative). model is set on AI usage deductions; is_streaming marks streaming-overage deductions.

Get Usage Dashboard

Combined current-month usage metrics with plan limits — the data behind the Settings → Usage page.

GET /api/v1/usage/dashboard

Auth: Bearer token required.

Response:

{
  "plan_id": "pro",
  "plan_name": "Pro",
  "ai_credit_vibeview": { "current": 0.25, "limit": 10.0, "unit": "USD" },
  "ai_tokens_byok": { "current": 60000, "limit": null, "unit": "tokens" },
  "streaming_minutes": { "current": 340, "limit": 1000, "unit": "minutes" },
  "active_sessions": { "current": 1, "limit": 2, "unit": "sessions" },
  "monthly_sessions": 87,
  "ai_cost_micro": 250000,
  "byok_cost_micro": 480000,
  "ai_runs": 30,
  "byok_runs": 15,
  "by_model": [
    { "model": "claude-4-sonnet", "runs": 30, "cost_micro": 250000 }
  ],
  "streaming_overage_minutes": 0,
  "streaming_overage_micro": 0
}

Each metric object has current, limit (null = unlimited), and unit. Streaming minutes include live in-progress sessions, so the number matches what the streaming meter enforces.