Plans, credits & usage

How credits work

• Each request that calls a model meters input + output tokens → USD (from the live price table) → credits.
• Default conversion: 1 credit = $0.01 (set CREDITS_PER_USD to change). Credits always round up, minimum 0.
• Pure-code tools cost 0 credits — e.g. mine_insights, list_*, organize tools. You only pay for model work.
• Each response carries X-Credits-Used and X-Tokens-Total headers; the body's meta.estimateCredits mirrors it.

Plans

Allowances reset each 30-day period; purchased top-ups roll over. Override per-plan amounts with PLAN_CREDITS_<PLAN> env vars when self-hosting.

Check your balance & usage

GET /api/v1/billing            -H "x-api-key: $MAVERA_API_KEY"
# → data.balance: { plan, used, allowed, remaining, ok }

GET /api/v1/usage?days=30      -H "x-api-key: $MAVERA_API_KEY"
# → data: { totals:{ inputTokens, outputTokens, costUsd, credits, modelCalls },
#           byTool:{ chat_with_audience:{credits,calls,costUsd}, … }, balance }

When you run out

Calls that would incur model cost return 402 PAYMENT_REQUIRED once the period allowance + top-ups are exhausted. Discovery and read endpoints keep working.

{ "ok": false, "error": { "code": "PAYMENT_REQUIRED", "message": "out of credits (250000/250000 used this period)" } }

Admin: change plan / add credits

  -H "x-admin-token: $MAVERA_ADMIN_TOKEN"   # or an OWNER/ADMIN API key
  -d '{ "workspaceId": "ws_…", "plan": "PRO" }'           # set plan
  -d '{ "workspaceId": "ws_…", "addCredits": 50000 }'     # top up (rolls over)