Every sample on every page follows this. Change it any time.

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

usage

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.

See costs by user

This is what everything cost since the 1st, in billed US dollars.

TypeScript
const byUser = await vestra.usage({ from: '2026-10-01', group_by: 'user' });console.log(byUser.total.spend_usd);

See one user's spend

TypeScript
const theirs = await vestra.user('traveller-42').usage();console.log(theirs.total.spend_usd);

Get a conversation's receipt

It lists every charge.

TypeScript
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.

TypeScript
await vestra.usage.caps({ user_monthly_usd: 20, alert_thresholds: [50, 80] });

See costs by user

This is what everything cost since the 1st, in billed US dollars.

Python
by_user = vestra.usage(from_="2026-10-01", group_by="user")print(by_user.total.spend_usd)

See one user's spend

Python
print(vestra.user("traveller-42").usage().total.spend_usd)

Get a conversation's receipt

It lists every charge.

Python
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.

Python
vestra.usage.caps(user_monthly_usd=20, alert_thresholds=[50, 80])

See costs by user

This is what everything cost since the 1st.

CLI
vestra usage --from 2026-10-01 --by user

Get a conversation's receipt

It lists every charge.

CLI
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.

CLI
vestra usage caps --customer-monthly 20 --alerts 50,80

See costs by user

This is what everything cost since the 1st, in billed US dollars.

HTTP
curl "$VESTRA_BASE_URL/v1/usage?from=2026-10-01&group_by=user" \  -H "Authorization: Bearer $VESTRA_API_KEY"

See one user's spend

HTTP
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.

HTTP
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.

HTTP
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
{  "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 usage4 routes, each with every field in the API reference
GET/v1/limitsThe day and month caps for the company and per user, the alert thresholds and the rate limits.Key scope: runtime (or all)
PATCH/v1/limitsSet 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/usageExact 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-itemsThe charges behind one task or one conversation, newest first: the receipt you can show your user.Key scope: runtime (or all)