---
title: Usage, savings and chargeback
description: Read your organisation's spend and volume, set the monthly spend cap, see cost per task and per project, find savings, and produce chargeback statements per key group, project, gear, key or member.
section: cloud
order: 30
audience: [user, operator]
sources: [services/nodejs-cloud/app/(console)/(shell)/usage, services/nodejs-cloud/app/(console)/(print)/usage/chargeback/statement/page.tsx, services/nodejs-cloud/components/usage/TaskViews.tsx, services/nodejs-cloud/lib/chargeback, services/nodejs-cloud/lib/savings, services/nodejs-cloud/lib/team-savings, services/nodejs-cloud/lib/usage/tasks.ts, services/nodejs-cloud/lib/projects]
features: [cloud.console-usage]
---

The Usage pages show what your organisation spent, on what, and how to spend less. They read metadata only (keys, models, tokens, cost), never request content.

| Page | What it is for |
|---|---|
| `/usage` | Spend and volume per day, key and model; the monthly spend cap; this month's forecast. |
| `/usage/tasks` | Cost per task: what each pull request, issue or tracker key cost. |
| `/usage/tasks/detail` | One task's cost (`/usage/tasks/detail?task=<task>&days=30`). |
| `/usage/projects` | Spend and budget envelopes per project. |
| `/usage/savings` | The savings plan: cheaper modes and commitments, with the math. |
| `/usage/team-savings` | What each key group saved this month. |
| `/usage/chargeback` | Cost statements per key group, project, gear, key or member, with CSV. |
| `/usage/chargeback/statement` | The same statement laid out for printing or saving as PDF. |

## Usage {#usage}

Pick a range of 7, 31 (default) or 92 days. The page shows:

- **Totals**: spend, requests, tokens in and out, requests cut short because the client left, service-tier savings, escalations this week, the share of input served from the prompt cache, and an approximate count of distinct sessions.
- **This month's forecast**: the run rate with weekday shape, a range, and the day it would cross the spend cap.
- **Charts**: spend per day by model, requests per day by key.
- **By key** and **By model** tables, each row linking into Requests with the same window.
- **Costliest sessions** (approximate).
- **Escalations this week**: cheap work retried on a stronger tier, the extra spend, how many succeeded, by reason.
- **Service tiers**: what flex and batch saved against the standard list price, and what priority cost on top.

Per-key and per-model figures are exact. Session rankings and distinct counts are approximate and labelled so.

### Monthly spend cap {#spend-cap}

The **Monthly spend cap** card shows month-to-date spend against the cap. Enter a cap in USD per month and **Save cap**; leave it empty for no cap. At 80% the console warns and the audit log records it. At the cap, `/v1` requests are refused with `429 spend_cap_reached` until the cap resets at the start of the next UTC month. Budgets per member, key, team, gear or project are on the [Budgets](/docs/cloud/console-budgets.md) page, and each product's daily AI limit on [AI spend](/docs/cloud/ai-spend.md).

## Outcomes this month {#outcomes}

Usage shows what Venom finished for your organisation this month, counted by the billing meters: Support conversations resolved by an approved AI reply (no reopen within 7 days), Venom Line calls handled to the end without a transfer, and Tasks issues an agent completed whose pull request merged. Each row has a count, the price per outcome and, for merged pull requests, the agent spend per accepted change from cost per outcome.

An outcome with no price is counted and shown but never billed. Settings, Billing lists every meter for the month with its quantity, unit price, amount and a month-end projection. Comms messages and call minutes bill only when they go through Venom's provider account; with your own Sinch or gateway they show as usage and cost nothing. Storage (Notes files today) is shown in GB and not billed yet. Nothing is per person or per agent.

## Cost per task {#tasks}

`/usage/tasks` totals what each task cost over the last 7, 30 (default) or 90 UTC days: its spend and share, sessions, members, a trend, and a link to GitHub or GitLab. It also shows spend on tasks against spend not on any task, per day. Each task opens `/usage/tasks/detail`, with its sessions costliest first, its spend by model, role and member, the cost trend, and a link to its requests in Requests.

A request counts toward the task it names in `x-venom-task`, else toward the first task its session named, so a session's turns from before the pull request existed, its subagents, side requests and retries all add up on the task. The venom CLI names the task itself: the pull request it opens with `gh pr create`, a task in the branch name (`123-fix-login`, `feature/ENG-142`), or `venom --task <url|id>`. Any other client sends the header:

```bash
curl https://cloud.usevenom.dev/v1/chat/completions \
  -H "Authorization: Bearer vck_…" \
  -H "x-venom-task: https://github.com/acme/web/pull/123" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "hello"}]}'
```

A task is a pull request or issue URL (GitHub, GitLab), `owner/repo#123`, a tracker key (`ENG-142`), or an id of letters, digits and `. _ : / # ! -`. On your machine, `venom cost --by task` shows the same totals for your key.

## Projects {#projects}

A project is the tag a request carries in `x-venom-project`, else its key's project (set a key's project under Settings, API keys). `/usage/projects` shows one card per project, those at their limit first: spend this month and all time, each budget envelope (daily, monthly or lifetime) with its bar, state and forecast, then the top members, models and costliest tasks over the last 30 days. Create envelopes on the [Budgets](/docs/cloud/console-budgets.md) page with **Applies to: Project**. The page refreshes every 30 seconds.

## Savings plan {#savings}

`/usage/savings` works out, from your own requests over 7, 14 or 30 (default) days, what you could save a month. It never asks a provider or a pricing page.

- The lead figure, with the one finding behind it.
- **Actions** ranked by dollars a month, each with a confidence in words, its math (inputs, the formula in words, the result), its assumptions, and its control: **Apply** (switch a gear role to a cheaper service tier), a link to the page that does it, or why it can't be applied here.
- **Commitments**: committed-use prices against your hourly traffic shape. Edit the price inputs, or reset them to Venom's default list prices.
- **Checked, not suggested**, and **Can't be priced**.

## Key group savings {#team-savings}

`/usage/team-savings` shows, for a month you pick, what each key group saved from the prompt cache, batch and flex tiers, local models, request dedup, cheapest routing and `venom-auto`, worked out from what the cloud already books. Totals: saved, share of the would-be bill, key groups saving at least a cent, and last month. Each key group gets its savings, trend, where they came from and one or two ways to save more, linked to the savings plan. It ranks key groups only, never a person. A key group holds API keys, daemons, policies and GPU grants, not people
(the API calls it `team`).

## Chargeback {#chargeback}

`/usage/chargeback` produces a cost statement for last month (default), this month so far, a named month or any range of whole UTC days (up to 366), grouped by key group, project, gear, key or member.

| Shown | Meaning |
|---|---|
| Spend, Requests | Totals for the period. |
| Cache savings | What the prompt cache saved, as booked per request (partly estimated where noted). |
| Largest | The group with the most spend and its share. |
| By group | Each group's spend and share, by model and by member. |

**Download CSV** exports the statement; each export is recorded in the audit log as `chargeback.exported`. **Printable statement** opens `/usage/chargeback/statement` without the console around it: the organisation, the period, totals, each group by model and by member, and the fine print. Use the browser's print dialog to save it as PDF.

If the period starts before the request log's retention, a notice says the first days are missing. If the spend ledger booked more than the request log shows, the page says so; statements count the request log, as billing does.

**Monthly statement by webhook**: when on, last month's statement goes to your webhook endpoints on the 1st of each month (UTC, from 06:00) as a `chargeback.statement` event, with totals, each group's spend, and links to the page and its CSV. Off by default. Pick the grouping, and add an endpoint that takes `chargeback.statement` under Settings, Webhooks.

## Who can do what {#roles}

| Action | Permission | Roles |
|---|---|---|
| See every Usage page | `usage:read` | owner, admin, developer, billing, viewer |
| Set the monthly spend cap; savings commitment prices; the monthly statement webhook | `billing:manage` or `org:manage` | owner, admin, billing |
| Apply a savings action to a gear role | `org:manage` | owner, admin |
| Open a task's captured requests | `logs:read` | owner, admin, developer, viewer |

## Troubleshooting {#troubleshooting}

| Symptom | Cause and fix |
|---|---|
| No usage in this range | No requests were booked in the window. Widen the range. |
| `429 spend_cap_reached` on `/v1` | The monthly cap is reached. Raise or clear it on `/usage`. |
| Every request is "Not on a task" | The client doesn't send `x-venom-task` and the branch name has no task. Use `venom --task`, or send the header. |
| A project has no spend | Requests carry no `x-venom-project` and the key has no project. |
| Changing the monthly statement needs billing:manage or org:manage. | Ask an owner, admin or billing member. |
| No endpoint takes `chargeback.statement` yet | Add or edit a webhook under Settings, Webhooks. |

## Related {#related}

- [Budgets and spend guards](/docs/cloud/console-budgets.md): limits per member, key, key group, gear and project.
- [Pricing and invoice reconciliation](/docs/cloud/console-prices.md): the prices these figures use.
- [Routing](/docs/cloud/console-routing.md): model choice and cheapest routing.
