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

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Account

Your company's account: who is calling, its keys, its caps, what it spent and the models it may use.

Send Authorization: Bearer vk_test_... on every call. Every route of Account.

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.

Your API key, scope runtime or all. On the card: usage. Every call here is a checked sample.

Request6 fields

Query

fromstringThe first day, inclusive, as YYYY-MM-DD (UTC). Absent: 29 days before to.
Type
string
tostringThe last day, inclusive, as YYYY-MM-DD (UTC). At most 31 days from from to to, counting both, so to is at most 30 days after from. Absent: today.
Type
string
group_by"day" | "user" | "deployment" | "conversation" | "task" | "model" | "category"How to split the spend: by day (the default), user, deployment, conversation, task, model or category.
Type
"day" | "user" | "deployment" | "conversation" | "task" | "model" | "category"
user_idstringOnly this user's spend, by your own id for them. Absent: every user's, and the company's own Bash's.
Type
string
deployment_idstringOnly this deployment's spend, by its dep_ id.
Type
string
conversation_idstringOnly this conversation's spend, by its conv_ id.
Type
string
Answers 2007 fields
object"usage"Always usage.
Type
"usage"
mode"live" | "test"The mode this spend is from: the mode of the key in use.
Type
"live" | "test"
fromstringThe first day counted, as YYYY-MM-DD (UTC).
Type
string
tostringThe last day counted, as YYYY-MM-DD (UTC).
Type
string
group_by"day" | "user" | "deployment" | "conversation" | "task" | "model" | "category"How the rows are split.
Type
"day" | "user" | "deployment" | "conversation" | "task" | "model" | "category"
dataobject[]One row per group, with what it spent.
keystringThe group, as group_by says: the day (2026-09-30), your user id, the deployment's, conversation's or task's id, the model, or the category. none when the spend belongs to no such thing; unknown for spend with no user.
Type
string
spend_usdnumberBilled US dollars, exact to 5 decimals. A group whose refunds exceed its charges reads 0.
Type
number
tasksintegerThe pieces of work that spent in this group. Bash's own replies are not counted as work.
Type
integer
totalobjectThe rows added up.
spend_usdnumberBilled US dollars across every row.
Type
number
tasksintegerPieces of work across every row.
Type
integer
TypeScript
const usage = await vestra.usage();
Python
usage = vestra.usage()
CLI
vestra usage
HTTP
# 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
{  "method": "tools/call",  "params": {    "name": "usage",    "arguments": { "from": "2026-10-01", "group_by": "user" }  }}