Usage and limits

Every billable unit (an AI call's tokens, an action, an email, a build, a database day) is recorded once, with what it cost to run (cost) and what the account is charged (billed).

#Pricing

billed is what the account pays: our cost plus a margin (AI +10 %, actions and email +30 %, the rest +20 %; your own AI key costs 0). It is drawn from the account's prepaid credits as it is recorded (Billing). Payment fees are not usage: they come off each payment.

#Limits

Per account (defaults):

Daily limits reset at midnight UTC (limits.resets_at). A limit error carries details saying which limit and when it resets.

#Usage, cost and limits

vibiz_usage (or GET /v1/usage, vibiz usage): what was spent in a period (24h, 7d, 30d, month; group by tool, model, project, api_key, end_user, day…) and today's limits:

• credits (prepaid accounts): balance_cents and status; at payment_required paid calls answer 402, see vibiz_billing.
• daily_spend: spent_usd, held_usd (reserved by calls in flight), limit_usd (the account's daily safety cap, $5 by default, raisable by the owner), remaining_usd. It resets at resets_at (midnight UTC); the 24h period is a rolling window, so it can differ slightly from the calendar day.
• projects: used / limit (10 by default). builds_today: per project, used / limit (30 a day). ai_budgets and email_today (50 a day): per project, when set or used.
• breakdown rows: billed_usd (what you are charged), cost_usd, units (tokens, calls, …).

Payments fees are not spend: they come off the payment itself (vibiz_payments get → fees).

Check it before costly work (AI, actions, many builds) and tell the user when remaining_usd is low.

#Read it

vibiz usage                         # today, by capability
vibiz usage --period 7d --by tool
vibiz usage --by end_user --project prj_…
vibiz usage --open                  # a signed link to the hosted dashboard

curl "https://app.vibiz.app/v1/usage?period=7d&group_by=tool" -H "Authorization: Bearer $VIBIZ_API_KEY"

{
  "object": "usage",
  "period": "7d",
  "totals": { "cost_usd": 0.42, "billed_usd": 0.42, "units": { "input_tokens": 120345 } },
  "data": [ { "tool": "ai.chat", "cost_usd": 0.31, "billed_usd": 0.31, "units": { … } } ],
  "limits": {
    "resets_at": "2026-10-26T00:00:00.000Z",
    "projects": { "used": 1, "limit": 10 },
    "daily_spend": { "spent_usd": 0, "held_usd": 0, "limit_usd": 5, "remaining_usd": 5, "used_pct": 0 },
    "builds_today": [ { "project_id": "prj_…", "used": 0, "limit": 30 } ],
    "email_today": [ { "project_id": "prj_…", "used": 0, "limit": 50 } ]
  }
}

group_by takes up to three of capability, tool, model, alias, project, api_key, end_user, day, outcome; filters project, model, tool, capability, end_user (or unattributed), api_key. model (and alias, the same) is the Vibiz model a call asked for, such as vibiz/fast; filter with model=vibiz/fast. GET /v1/projects/:id/usage is the same for one project. GET /v1/metrics has request counts, error rate and latency per capability.

End users: pass your own user's id (a stable pseudonymous id, not an email) as user on AI calls or X-Vibiz-User on anything else, or use vibiz.user(id) in @vibiz/app; usage then breaks down by end user, and end_user_daily_budget_usd caps each one's AI spend per day.

#What agents can and can't do

Agents read usage (vibiz_usage) and should before costly work. Creating named keys is an owner's.