# Dashboards and usage by metadata in Limitr Cloud

> Limitr Cloud dashboards: usage, cost, value, and margin from your calls, broken down by the metadata your calls carry and by groups like tasks, with how every number is calculated, views from the Analyst, and saved dashboards.

# Dashboards

**Dashboards** show usage, cost, value, and margin from your calls, in the current mode. With a segment selected in
the top bar, panels about customers (and groups, calls, events, and invoices) show only its customers; daily and
metadata totals are for the whole workspace, and say so. Every panel can show **How this is calculated**: the data
it read (and whether it's exact or sampled) and the math, so a number is never a mystery.

Four come with every paid workspace:

| Dashboard | Shows |
|---|---|
| **Overview** | Calls, cost, and value over the last 30 days |
| **Usage** | Usage by entitlement, by hour, and top customers |
| **Overage and denials** | Usage past the limits, what it bills, and denied calls |
| **Attribution** | Cost and value by call metadata and by group |

Cost is what calls cost you (the overhead your policy sets, or what your app reports). Value is usage at your
prices, and billed is what overage charges.

## Usage by metadata

Pass metadata with a call, and Cloud breaks usage down by it:

<Tabs groupId="lang" queryString>
<TabItem value="typescript" label="TypeScript">

```ts
await limitr.allow('org_acme', 'ai_tokens', tokens, {
    model: 'standard',
    workflow: 'support',
    task_id: 'task_8812',
});
```

</TabItem>
<TabItem value="python" label="Python">

```python
limitr.allow('org_acme', 'ai_tokens', tokens, {
    'model': 'standard',
    'workflow': 'support',
    'task_id': 'task_8812',
})
```

</TabItem>
</Tabs>

Settings > **Usage metadata** lists the keys your calls carry, a few seconds after they arrive, with the values
seen. For each key:

- **Group** adds calls up by that key, Ex. `task_id`, so you can see what a whole task cost and what it earned,
  across all of its calls. It counts from when you turn it on, and works for text keys. Use it for keys that identify
  a unit of work.
- **Hide** stops keeping a key at all (Ex. something you'd rather not store).

Each key keeps its first values (the number depends on your plan); later ones count as "(other)". Keys that look like
IDs (Ex. a request ID) are counted but not broken down. Changing these needs the **Change customers** permission.

## By account or by customer

A customer is one row of usage; an [account](./customers#accounts) is who's billed (an org with its teams and
users, or several companies billed together). Ask for either: "revenue by account this quarter", "Acme's usage by
user", "which accounts are overdue". Panels about customers carry each one's account, so the Analyst can roll them up
by account or show one account's members, and it has the accounts themselves (members, how each bills, its
contracts) and their invoices (every bill: due, paid, overdue, true-ups, prepaid draws) to chart and list.

The Analyst reads everything Cloud keeps, and picks what answers the question:

| Ask about | It reads |
|---|---|
| Usage, cost, and margin, by day, entitlement, metadata, or task | every call |
| Revenue and margin per customer | each [customer's invoice](./customers#invoices) |
| What was billed, what's due or overdue, revenue per account | each [account's invoice](./customers#invoices): every bill |
| Cash collected, refunds, failed or waiting charges, top-ups bought | the charges themselves |
| Credits given and credit balances | [credits](./customers#credits-and-refunds) |
| This period so far | customers' and accounts' ledgers |
| Contract value, deferred revenue, renewals | [contracts](#contracts) |
| What's next, or what a change would do | forecasts and replays |

A customer's invoice and its account's invoice count the same money, so a chart uses one or the other, never both.

## Contracts

The Analyst can chart and list your [contracts](./contracts) too: "total contract value", "contracted ARR by
account", "deferred revenue this quarter", "contracts ending in the next 90 days". Each contract comes with where it
stands, who it's with, its term and the days left, its value as stated, a year, and for the whole term, its fees and
commitment, and what it has billed, earned, and has deferred so far. A contract's value is what was agreed; what it
billed is what your invoices say, and each contract says whether its fees and commitment come to its value.

## Views from the Analyst

Ask the Analyst for a picture ("margin by workflow this week", "which customers cost us the most per task") and it
shows a view in the conversation. **Open full width** shows it as a dashboard, and on Scale and Enterprise **Save as dashboard**
keeps it for your team. To change one, choose **Change with the Analyst**.

## Forecasts and what-ifs

On Scale and Enterprise, the Analyst can look ahead (Scale forecasts from up to 90 days of history and 90 days ahead; Enterprise's are enhanced, on the largest model, from a year of history and up to 180 days ahead):

- **Forecasts.** "How much chat usage next month?", "Forecast our margin through January." Usage, cost, what's
  billed, and margin ahead, from your recent days (the trend and the weekday pattern), with the range they're likely
  to land in. The forecast is drawn dashed after the actual days.
- **Who will hit a limit.** Each customer's usage projected to the end of their billing period against their limit:
  who will hit it, around when, and what their overage would bill.
- **What a pricing change does.** Put the change in your draft (or ask the Analyst to), then ask "what would last month's
  bills look like with this?". Each customer's real billing period is priced again under the draft, by the same
  code that makes invoices, next to what they're billed today, with the change for each customer and in total.
  Nothing is saved or charged. It can project each period to its end first.

A forecast is fitted to what already happened: new customers, launches, and price changes aren't in it, and "How
this is calculated" says what it used. Treat it as a guide, not a promise.

## Saved dashboards

On Scale and Enterprise, dashboards the Analyst builds can be saved and are shared with your workspace. Each is a small
[Stof](/docs/tutorial/stof) document: **Stof** opens it to read or edit, and **Run** shows the result before you save.
Deleting one removes it for everyone; its data isn't affected.
