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 checkout (sold through Link, Stripe’s merchant of record; tax is calculated at 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 next refills: the 1st of next month (UTC) on the Free plan, the end of the current billing period on a paid plan, or null when no refill is scheduled.
• low_balance — server-computed flag for showing a low-balance warning. Always false on the Free plan, whose whole monthly allowance is below the warning threshold.
• 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 → Plan and usage page.

GET /api/v1/usage/dashboard

Auth: Bearer token required.

Response:

{
  "plan_id": "pro",
  "plan_name": "Business",
  "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,
  "builds_total": 4,
  "build_minutes_used": 26,
  "build_minutes_included": 2000,
  "build_minutes_billed": 0,
  "build_cost_micro": 0,
  "storage": { "current": 1250000000, "limit": 250000000000, "unit": "bytes" },
  "month_start": "2026-09-01T00:00:00",
  "month_resets_at": "2026-10-01T00:00:00",
  "allowance_period_start": "2026-09-10T14:02:11",
  "allowance_resets_at": "2026-10-10T14:02:11"
}

Timestamps are UTC. Every figure covers the calendar month from month_start to month_resets_at, except ai_credit_vibeview, which is the plan allowance spent since its last refill: allowance_period_start to allowance_resets_at. That window is the calendar month on the Free plan and the billing period on a paid plan. Both allowance fields are null when no refill is scheduled.

plan_id is the plan’s stable id (free, dev, starter, pro); plan_name is its display name (Free, Solo, Team, Business). Match on plan_id.

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.

Cloud builds are billed by the minute: build_minutes_used is the included build minutes used this month out of build_minutes_included, build_minutes_billed the minutes billed to usage credit past them, and build_cost_micro what builds cost this month. These replace the older builds_free_used and builds_free_quota.