# 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://thelastapi.dev/docs/billing)). Payment fees are not usage: they come off each payment.

## Limits

Every cap, its default, and how the owner changes it:

| Limit | Default | Change it | Past it (`details.reason`) |
| --- | --- | --- | --- |
| Daily spend (AI, actions, texts, calls) | $5 per account per UTC day | console ▸ Billing ▸ Daily safety cap, or `PATCH /v1/billing {"daily_spend_limit_usd": 50}` (up to $1,000) | `429`, `daily_spend` |
| Project AI budget | $1 per project per UTC day | console ▸ project ▸ AI ▸ Daily AI budget, or `PATCH /v1/projects/:id/ai {"daily_budget_usd": 10}` (`null`: no project budget) | `429`, `project_budget` |
| Projects | Free plan 2, Pro 10 | delete one, or write to support@vibiz.ai | `403`, `project_limit` |
| Builds | 30 per project per UTC day | fixed (write to support) | `429`, `daily_builds` |
| App email | 50 per project per UTC day | fixed while the address builds its reputation; send newsletters as broadcasts | `429`, `email_daily_limit` |
| Emails agents may send | none (the owner presses Send) | project ▸ Email ▸ Settings, or `PATCH /v1/billing {"agent_email_limit_per_month": 5000}` | `403`, `over_agent_limit` |
| Texts / calls | 200 texts and 50 calls per project per UTC day | fixed | `429`, `phone_daily_limit` / `phone_daily_call_limit` |
| Credits | the account's balance | add credits or turn on auto-recharge in Billing | `402 payment_required`, see [Billing](https://thelastapi.dev/docs/billing) |
| AI per key | see [AI](https://thelastapi.dev/docs/ai#limits) | | `429` with `Retry-After` |

Daily limits reset at midnight UTC (`limits.resets_at`). A refusal carries `details` saying which limit, the limit and usage, when it resets, `raise_url` (the console page that changes it, field focused) and `next_step` (what to tell the owner).

## Limit alerts

Nobody's app should stop without its owner knowing. For every cap above:

- **At 80 %** the account's owners get one email ("You've used 82% of your daily spend limit: raise it?"), and **at 100 %** (or when a request is refused) one more. Once per cap, project and day (month for monthly caps); a raised limit re-arms it.
- Each email says what (which cap, which project), why (usage against the limit, what stops, when it resets) and how to fix it, with the link that opens the exact setting.
- The console shows the same on **Overview** and **Usage** while a cap is at 80 % or more, with a **Raise it** button.
- `GET /v1/usage` → `limits.alerts` lists them for agents: `cap`, `level` (`warning` or `reached`), `used`, `limit`, `message`, `fix`, `raise_url`.
- An owner turns one kind of email off in **Billing ▸ Limit alerts** or with `PATCH /v1/billing {"limit_alerts": {"daily_builds": false}}`. All are on by default.

**Agents building an app:** tell the owner the caps it will run under and what you expect it to cost a day, set the project AI budget to fit the expected traffic, and if the app adds a cap of its own keep it under the platform's and make it tell the owner. An app must never stop silently.

## 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://thelastapi.dev/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 thelastapi 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.
