# usage

> See what each job and user cost, and set caps and alerts.

See what every job and every user cost, in billed US dollars, grouped the way you need. You can also set spending caps and alerts. Line items are the itemized receipt for one conversation or one task, ready to show your user.

## TypeScript

```ts
// See costs by user. This is what everything cost since the 1st, in billed US dollars.
const byUser = await vestra.usage({ from: '2026-10-01', group_by: 'user' });
console.log(byUser.total.spend_usd);

// See one user's spend.
const theirs = await vestra.user('traveller-42').usage();
console.log(theirs.total.spend_usd);

// Get a conversation's receipt. It lists every charge.
const receipt = await vestra.usage.lineItems({ conversation: 'conv_8f2k' });
console.log(receipt.data.length);

// Set caps and alerts. This sets a monthly cap for each user, with alerts at 50% and 80% of it.
await vestra.usage.caps({ user_monthly_usd: 20, alert_thresholds: [50, 80] });
```

## Python

```python
# See costs by user. This is what everything cost since the 1st, in billed US dollars.
by_user = vestra.usage(from_="2026-10-01", group_by="user")
print(by_user.total.spend_usd)

# See one user's spend.
print(vestra.user("traveller-42").usage().total.spend_usd)

# Get a conversation's receipt. It lists every charge.
print(len(vestra.usage.line_items(conversation="conv_8f2k").data))

# Set caps and alerts. This sets a monthly cap for each user, with alerts at 50% and 80% of it.
vestra.usage.caps(user_monthly_usd=20, alert_thresholds=[50, 80])
```

## CLI

```bash
# See costs by user. This is what everything cost since the 1st.
vestra usage --from 2026-10-01 --by user

# Get a conversation's receipt. It lists every charge.
vestra usage items conv_8f2k

# Set caps and alerts. This sets a monthly cap for each user, with alerts at 50% and 80% of it.
vestra usage caps --customer-monthly 20 --alerts 50,80
```

## HTTP

```bash
# See costs by user. This is what everything cost since the 1st, in billed US dollars.
curl "$VESTRA_BASE_URL/v1/usage?from=2026-10-01&group_by=user" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# See one user's spend.
curl "$VESTRA_BASE_URL/v1/usage?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Get a conversation's receipt. It lists every charge, newest first.
curl "$VESTRA_BASE_URL/v1/usage/line-items?conversation_id=conv_8f2k" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Set caps and alerts. This sets a monthly cap for each user, with alerts at 50% and 80% of it.
curl -X PATCH "$VESTRA_BASE_URL/v1/limits" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_monthly_usd": 20, "alert_thresholds": [50, 80] }'
```

## MCP

```json
{
  "method": "tools/call",
  "params": {
    "name": "usage",
    "arguments": { "from": "2026-10-01", "group_by": "user" }
  }
}
```

## Good to know

### Grouping costs

`group_by` can be `day`, `user`, `deployment`, `conversation`, `task`, `model` or `category`. `from` and `to` are dates.

### Caps and alerts

You can set daily and monthly caps, for your company as a whole and for each user, and alert thresholds as percentages of a cap. Your webhooks receive `usage.threshold_reached` and `usage.cap_reached`.

### Late charges

A task's last charges can arrive a few seconds after it ends. `cost_complete: false` means more charges are coming. You see it on `message.completed` and on a run's `cost()`.

## The routes behind usage

- `GET` [/v1/limits](https://vestra.ai/developers/reference/api/account/get-v1-limits.md): The day and month caps for the company and per user, the alert thresholds and the rate limits. Key scope: `runtime` (or `all`).
- `PATCH` [/v1/limits](https://vestra.ai/developers/reference/api/account/patch-v1-limits.md): Set the day and month caps for the company and per user, and the alert thresholds, within what Vestra allows. Key scope: `admin` (or `all`).
- `GET` [/v1/usage](https://vestra.ai/developers/reference/api/account/get-v1-usage.md): Exact billed spend and real task counts, by day, user, deployment, conversation, task, model or kind of spend, filtered by user, deployment or conversation. An erased user's spend stays in the totals, as the user unknown. Key scope: `runtime` (or `all`).
- `GET` [/v1/usage/line-items](https://vestra.ai/developers/reference/api/account/get-v1-usage-line-items.md): The charges behind one task or one conversation, newest first: the receipt you can show your user. Key scope: `runtime` (or `all`).

Next: [`keys`](https://vestra.ai/developers/keys.md)