# GET /v1/usage

> Exact billed spend and real task counts, by day, user, deployment, conversation, task, model or kind of spend, filtered by user, deployment or conversation.

In [Account API](https://vestra.ai/developers/reference/api/account.md): 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.

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.

Your API key, scope `runtime` or `all`. On the card: [`usage`](https://vestra.ai/developers/usage.md). Every call here is a checked sample.

## Request

Query:

- `from` (`string`): The first day, inclusive, as YYYY-MM-DD (UTC). Absent: 29 days before `to`.
- `to` (`string`): The 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.
- `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`.
- `user_id` (`string`): Only this user's spend, by your own id for them. Absent: every user's, and the company's own Bash's.
- `deployment_id` (`string`): Only this deployment's spend, by its `dep_` id.
- `conversation_id` (`string`): Only this conversation's spend, by its `conv_` id.

## Answers 200

- `object` (`"usage"`): Always `usage`.
- `mode` (`"live" | "test"`): The mode this spend is from: the mode of the key in use.
- `from` (`string`): The first day counted, as YYYY-MM-DD (UTC).
- `to` (`string`): The last day counted, as YYYY-MM-DD (UTC).
- `group_by` (`"day" | "user" | "deployment" | "conversation" | "task" | "model" | "category"`): How the rows are split.
- `data` (`object[]`): One row per group, with what it spent.
  - `key` (`string`): The 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.
  - `spend_usd` (`number`): Billed US dollars, exact to 5 decimals. A group whose refunds exceed its charges reads 0.
  - `tasks` (`integer`): The pieces of work that spent in this group. Bash's own replies are not counted as work.
- `total` (`object`): The rows added up.
  - `spend_usd` (`number`): Billed US dollars across every row.
  - `tasks` (`integer`): Pieces of work across every row.

## Code

**TypeScript**

```ts
const usage = await vestra.usage();
```

**Python**

```python
usage = vestra.usage()
```

**CLI**

```bash
vestra usage
```

**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" }
  }
}
```