> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/track-and-control-costs/build-custom-dashboards-and-charts.md).

# Build Custom Dashboards & Charts

Revenium's Intelligence dashboards answer the most common questions about AI spend and performance. Custom dashboards and charts go further — giving you the flexibility to build exactly the views your business needs, scoped to the metrics, customers, agents, and time windows that matter to your team right now.

Find your dashboards under **My Dashboards** in the left sidebar, and your custom charts under **Chart Builder**.

***

### <i class="fa-square">:square:</i> Dashboards

A dashboard is a collection of charts organised around a purpose. The most useful ones are built with a specific audience in mind — a weekly finance review, a post-incident engineering debrief, a per-customer profitability summary for your account team.

#### Finding Your Dashboards

**My Dashboards** shows each of your dashboards as a card. A card carries a thumbnail of the charts on the dashboard, the names of those charts (hover over them to see the full list), how many charts it holds and when it was last edited. Click a card to open its dashboard. An empty dashboard's card takes you straight to adding charts.

Search by dashboard name or by the name of a chart on it, and sort by **Last edited**, **Name** or **Most charts**. Star the dashboards you use most to keep them at the top. Switch between **Grid** and **List** to see your dashboards as cards or as a table.

Each card has a menu with **Open**, **Edit**, **Duplicate** and **Delete**. Duplicate creates a new dashboard with the same charts, named after the original with "(copy)" added. If you have read-only access, the menu offers **Open** only.

#### Building a Dashboard

1. Click **Add Dashboard** and give it a name and description that will mean something to whoever opens it.
2. Click **Add chart** to open the chart picker. The **Catalogue** tab holds the pre-built library and the **Custom charts** tab holds the charts you saved in Chart Builder. Both tabs are searchable, each chart shows a thumbnail, and you can preview a chart before adding it. Charts already on the dashboard are marked **Added**.
3. Arrange your charts on the canvas, then hit **Done Editing** when you're ready. Layout changes continue saving even if a background refresh fails.

Each chart can be shared, exported as a PNG or CSV, or copied to your clipboard directly from the dashboard.

#### Deleting a Dashboard

To remove a custom dashboard, choose **Delete** from its card's menu in **My Dashboards**. Deleting asks you to confirm first, so a dashboard isn't removed by accident. The built-in Intelligence views are not listed in My Dashboards and can't be deleted, so managing your own custom views never puts the standard reporting at risk.

#### The Pre-Built Chart Library

The library covers the most common reporting needs across cost, revenue, performance, and profitability. A few highlights:

* **Customer Cost Over Time** — how spend per customer trends day by day, useful for spotting who's growing fastest before it becomes a billing conversation.
* **Customer Profitability** — cost against margin per customer, so you can see at a glance who's profitable and who isn't.
* **Task Performance by AI Model** — cost and time per task broken down by model, for validating whether a model change is actually performing better.
* **Token and Tool Cost** — separates raw token spend from external tool call costs over time, essential for agentic workflows where tool costs frequently dwarf token costs.
* **Revenue / Product** — revenue generated per product tier, for pairing against cost data to get to true margin.
* **Provider Comparison** — a prefilled template that opens in the Chart Builder with provider billing and metered usage placed together, so you can line up what a provider bills against the usage Revenium meters for it without building the view from scratch. Add it to any dashboard like any other chart, then adjust the metric, grouping, filters, or time window to fit your team.

<figure><img src="https://136027078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXLC45kYkVPv2AtO7QLvg%2Fuploads%2Fgit-blob-8dfb53ac849c68b823a05faa50208147ee94b5dd%2FScreenshot%202026-04-28%20at%2015.58.05.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

***

### <i class="fa-pen">:pen:</i> Custom Charts

For more specific questions — the metric combination that maps to how your team thinks, or a view scoped to a single customer, agent, or environment — the chart builder gives you full control.

Head to **Chart Builder** to see your saved charts as a gallery. Each card shows a thumbnail, a short summary of what the chart measures, a **Telemetry** or **Billing** badge for its data source, and when it was last edited. Search your charts, switch between **Grid** and **List**, and use a card's actions to **View**, **Edit**, **Clone** or **Delete** a chart. Clone opens a copy in the builder, named after the original with "(Clone)" added, ready to adjust and save.

Click **Create chart** to open the builder. The settings are grouped into sections:

* **Data**: the data source (**Telemetry**, what your SDKs and coding assistants report, or **Provider billing**, what providers invoice), the metric and the calculation.
* **Shape**: the chart type (Line, Column, Bar or Pie) and whether it reads **Over time** or as **Totals**.
* **Time**: the window and the resolution.
* **Breakdown**: how the chart is grouped into series.
* **Filters**: the slice of data the chart covers.
* **Focus**: show everything, the top N groups, or only groups above a value.
* **Scope**: for telemetry charts, whether coding assistant usage counts as spend.

On a wide screen, a rail beside the settings lets you jump to any section. The preview beside the settings shows the chart card as it will appear on a dashboard, with its name, a sentence describing what it shows, and the filters applied. It draws on sample data until you name the chart, then on your live data. Switch between **Sample data** and **Live data** at any time, and use **Refresh** to redraw it. A new chart also offers **Start from** shortcuts, such as Cost over time, Cost by provider and Top 10 models, that fill in the settings for you to adjust. If you close the builder with unsaved changes, it asks before discarding them.

#### Your Metric

The base metrics cover everything Revenium tracks: Total Cost, Request Count, Token Count (input and output separately), Latency, Error Count and Rate, Image Count, Duration, Character Count, and Credits Consumed.

Pair that with a calculation — Total, Average, Per-Request Average, Per-Token Average, Per-Entity Average, Median, or Maximum — and the question your chart answers becomes precise. Total Cost tells you how much you spent. Per-Request Average tells you whether efficiency is improving.

#### How the Data is Grouped

The Primary Group By controls how the data is sliced — by Customer, Model, Provider, Agent, Product, Task, Subscriber, Department, or Modality. This is where a single metric becomes a genuinely useful view. Total Cost grouped by Agent shows which agents are burning the most. Error Rate grouped by Model tells you whether a particular model is underperforming. Latency grouped by Task shows which operations are slow regardless of which model handles them.

Grouping by Department puts each person's spend under the department they sat in when the usage happened, so a person in a sub-department shows under that sub-department, not under its parent. Spend with no person behind it, or with a person who has no department, appears as one Unattributed bar. When a chart is scoped to one department, people in its sub-departments roll up to the sub-department directly under that scope.

A chart grouped by Department or Subscriber shows the 8 largest groups, whatever Focus is set to, and puts all the remaining groups into one **Other** bar. The chart preview caption tells you how many groups exist, for example "Top 8 of 40", so a subset is never presented as the whole picture. A pie chart left on Focus **Everything** shows up to 50 slices, with **Other** for groups folded out of view. Open **Other** to see those groups. When many groups are folded, the list shows the largest of them and says how many it includes out of the total. When the calculation is an average, the pie shows values without implying that slices are shares of one total.

#### Filters

Filters let you scope a chart to exactly the slice of data you care about — a specific customer, a single environment, a particular task type, an error reason, or only streamed responses. A chart tracking Total Cost by Model is useful. The same chart filtered to your production environment and scoped to a single customer tier is actionable.

#### Time Window

Date ranges run from the last hour through to the last 365 days, with a custom range for anything in between. **Resolution** offers the steps that fit the window, from five minutes for the last hour up to monthly for the longest windows, or Auto for Revenium to choose the most readable one.

> **💡 Tip:** Once saved, any custom chart is available to add to any dashboard — giving you a reporting layer that reflects exactly how your team thinks about AI performance, not just how the platform does.

***

### <i class="fa-building">:building:</i> Examples Worth Building

**"Is our Enterprise tier profitable?"** Total Cost, grouped by Product, filtered to your Enterprise tier — alongside a Revenue / Product chart on the same dashboard to see margin in context.

**"Which customers are consuming disproportionately?"** Total Cost, Per-Entity Average calculation, grouped by Customer, Focus set to Top N. Surfaces the highest-consuming customers without the rest of the data obscuring them.

**"Is this agent getting more expensive over time?"** Total Cost, grouped by Agent, filtered to a specific agent, Line Chart over Last 90 Days. A rising line not matched by a rise in request count is a signal worth investigating.

**"Where are errors actually happening in production?"** Error Rate, Average calculation, grouped by Model, filtered to your production environment. Shows which models are failing where it matters, not just in aggregate.

***

### <i class="fa-filter">:filter:</i> Filter Values over the API

If you build your own reports on the analytics API, the filter options calls give you the values your filters can take. Each returns the distinct values that appear in your data for a time window, the same lists the filter pickers in the app show. There is one call per list: agents, API keys, customers, model sources, models, organizations, products, providers, task types, teams, tool providers, tools, users and vendors. Lists of things you manage, such as customers, organizations, products and API keys, return an id with each name.

Pass `startDate` and `endDate` as ISO 8601 timestamps. Without them, the window is the last 24 hours. Send your key as a bearer token. A read-only or full-access key works. A metering-only key is refused. The team comes from the key, so there is no `teamId` parameter.

The values are in `_embedded.items`. See [available models](https://revenium.readme.io/reference/get_available_models) and [available users](https://revenium.readme.io/reference/get_available_users) in the API reference for the full response, and the other lists beside them.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/track-and-control-costs/build-custom-dashboards-and-charts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
