---
title: Usage & Costs Dashboard
description: Track token consumption and estimated costs for every agent on your Pinchy instance.
---

import { Aside, Badge } from "@astrojs/starlight/components";

Pinchy keeps a running tally of how many tokens each agent burns through and what they roughly cost. The Usage Dashboard at `/usage` is where admins go to answer "where is the money going" without leaving the platform or stitching together provider invoices.

:::note[Enterprise features on this page]
The **Per-User Breakdown** and **CSV Export** are Pinchy Enterprise features. Everything else works without a license. See [Enterprise Setup](/guides/enterprise-setup/).
:::

## Who can see it

Admins only. Non-admin users get redirected to the home page if they try to open `/usage` directly.

## What you see

![Usage & Costs dashboard with token totals, cost estimate, and per-agent breakdown](/screenshots/usage-dashboard.png)

Open **Usage** from the sidebar (or visit `/usage`).

- **Total Tokens** — sum of input and output tokens for the selected period and agent filter
- **Estimated Cost** — running USD estimate based on the per-token prices in your provider's model config. Shows "—" when pricing is unavailable (e.g. local Ollama models) so you can tell the difference between "free" and "no pricing data"
- **Cache Tokens** — combined cache read and write tokens, shown when cache usage exists. Cache tokens reduce costs (reads are cheaper than fresh input tokens) and this card helps you see how much you're saving
- **Source Breakdown** — how those tokens split across Chat, System, and Plugin use (see below)
- **Daily Token Usage** chart — input vs output tokens over time. Days with no usage show as zero instead of being skipped, so you see actual gaps rather than misleading interpolation. The chart groups days by your browser's timezone, not UTC
- **Per-Agent Breakdown** — which agents consume what, sorted by cost. Deleted agents are marked with "(deleted)" so you can still see their historical usage
- **Per-User Breakdown** <Badge text="Enterprise" variant="note" /> — same numbers split by who chatted with the agent

### Token sources

Not every token an agent burns comes from a user message. Pinchy labels each usage record with its source so you can see where the budget actually goes:

- **Chat** — tokens spent on direct conversations with the agent (user messages and the agent's replies).
- **System** — tokens spent on background work Pinchy triggers on the agent's behalf, such as onboarding interviews or scheduled jobs. No human sent these messages.
- **Plugin** — tokens spent _inside_ a tool call. For example, when an agent asks the `pinchy-files` plugin to read a PDF, the plugin may call a vision model to extract text from scanned pages. Those vision calls are billed to the agent but show up under Plugin, not Chat.

Cards for each bucket only appear when that bucket has non-zero usage, so a fresh instance only shows Chat until background or plugin work kicks in.

### Filters

- **Time period**: 7 days, 30 days, 90 days, or all time
- **Agent**: drill down to a single agent, or look at the whole fleet

Both filters apply to every card and tab on the page.

## Where the numbers come from

Pinchy writes a usage record whenever an LLM call completes — both for chat turns (captured by a background poller that reads OpenClaw session snapshots) and for plugin-internal LLM calls (reported directly by the plugin). Each record carries the input/output tokens the provider reported, plus cache read and write tokens when the provider supports prompt caching.

Pinchy multiplies those by the per-million-token prices configured for the model and stores the result in USD with six decimals. Cache tokens use Anthropic-style pricing ratios: cache reads at 10% of the input price, cache writes at 125%.

A few honest caveats:

- **It's an estimate.** Provider invoices are the source of truth. Pinchy uses the prices baked into the OpenClaw model config, which can drift from a provider's current published rates.
- **Cache pricing is approximate.** The 10%/125% ratios match Anthropic's published pricing. If your provider uses different cache pricing, the estimate will be off. The token counts themselves are always accurate.
- **Local Ollama shows "—" for cost.** Local models record token counts but have no pricing config. The dashboard shows a dash instead of $0.00 to make this clear.
- **Tool execution time isn't tracked here.** Only the LLM tokens count. The Audit Trail at `/audit` is where you go for tool-use details.

## Export <Badge text="Enterprise" variant="note" />

With an active Enterprise license, the **Export CSV** button (top-right) downloads the current view — period and agent filter applied — as a CSV file. The export includes cache read and write tokens alongside the regular token columns. Useful for finance hand-offs or feeding the data into your own dashboards.

Without a license, the button is disabled but stays visible so you know the feature exists.

## What it can't do

The dashboard answers "how much" and "by whom", not "for what". If you need to know which conversation burned through 50,000 tokens, that level of detail lives in the Audit Trail (`/audit`) — and even there, individual chat content is intentionally not logged. Pinchy treats chat messages as user data, not audit material.
