# GET /v1/usage/line-items

> The charges behind one task or one conversation, newest first: the receipt you can show your user.

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.

The charges behind one task or one conversation, newest first: the receipt you can show your user.

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:

- `limit` (`integer`): How many items per page, 1 to 100. Default 20.
- `cursor` (`string`): Where to go on from: the `next_cursor` of the page before, unchanged. Absent: the first page.
- `task_id` (`string`): The charges behind this piece of work, by its `task_` id. Send this or `conversation_id`.
- `conversation_id` (`string`): The charges behind this conversation, by its `conv_` id. Send this or `task_id`.

## Answers 200

- `data` (`object[]`): The items on this page.
  - `id` (`string`): The charge's id.
  - `object` (`"usage.line_item"`): Always `usage.line_item`.
  - `category` (`"orchestrator" | "intelligence" | "tools" | "compute" | "background" | "voice"`): The kind of spend: `orchestrator` (Bash's replies), `intelligence` (its thinking at work), `tools`, `compute`, `background` or `voice`.
  - `amount_usd` (`number`): Billed US dollars; a refund is negative. A subject's items add up to its `cost_usd`.
  - `model` (`string | null`): The model the charge was for; null when it was for no model.
  - `description` (`string`): What the charge was, in a few fixed words such as `Work by Bash`; a refund starts `Refund: `.
  - `created_at` (`string`): When it was charged, as an ISO 8601 date and time in UTC.
- `next_cursor` (`string | null`): Send it as `cursor` for the next page; null on the last page.

## Code

**TypeScript**

```ts
const receipt = await vestra.usage.lineItems({ conversation: 'conv_8f2k' });
```

**Python**

```python
receipt = vestra.usage.line_items(conversation="conv_8f2k")
```

**CLI**

```bash
vestra usage items conv_8f2k
```

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