# Usage and limits

> What the account used and what it cost, per tool, model, project, key or end user, and how close it is to today's 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](https://app.vibiz.app/docs/billing)). Payment fees are not usage: they come off each payment.

## Limits

Per account (defaults):

| Limit | Default | Past it |
| --- | --- | --- |
| Projects | 10 | `rate_limited` on create |
| Builds | 30 per project per UTC day | `rate_limited` |
| Spend on AI and actions | $5 per account per UTC day (an owner raises it in Billing) | `rate_limited`, `details.reason: "daily_spend"` |
| Credits | the account's balance | `payment_required` (402), see [Billing](https://app.vibiz.app/docs/billing) |
| Email | 50 per project per UTC day | `rate_limited` |
| AI per key | see [AI](https://app.vibiz.app/docs/ai#limits) | `rate_limited` with `Retry-After` |

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

```bash
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
```

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

```json
{
  "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.