> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/dispatch/cost-and-insights/cost-reporting.md). # Cost Reporting Build your own breakdown of spend, savings and traffic, then bookmark it, export it, or share it with people who can't sign in Overview answers one fixed question: what the last 30 days cost. **Cost Reporting is for the next question**, the one Overview didn't answer. Pick the figures you want, choose what to break them down by, narrow it to the rows you care about, and choose the period. The result is a table and chart you can bookmark, download as CSV, or share. Cost Reporting answers for whoever is reading it. A **Dispatch User** reports on the keys they own. A **Dispatch Admin** reports on the whole organization. {% hint style="success" %} **From a hunch to a spreadsheet in a few clicks**: Open **Spend › By tag** to see which project is costing the most, switch to **Usage › Business unit by tier** to see which tiers it runs on, then **Export › Full report** for finance. If finance can't sign in, **Share › Share with anyone** gives them a read-only link with live figures that expires on its own. {% endhint %} ## What You Can Report On | | Dispatch User | Dispatch Admin | | ----------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | | Whose spend | The keys you own | Every key in the organization | | Page description | "Spend, savings and traffic for the keys you own" | "Spend, savings and traffic for the organization" | | Build, filter and export reports | ✓ | ✓ | | **Copy link** to the report | ✓ | ✓ | | **Share with anyone** (a public, expiring link) | — | ✓ | Your role sets the scope, and nothing you choose in the report can widen it. A Dispatch User can still group by **Key owner**, but the report only ever contains one owner: you. ## Starting Points Across the top, three tabs, **Spend**, **Savings** and **Usage**, hold ready-made reports. Click one to load it. The one on screen stays highlighted, and once you change it the row shows **Custom report** instead. Loading a starting point keeps the **Period** you've already chosen. | Tab | Starting point | What it answers | | ----------- | -------------------------- | ------------------------------------------------------------ | | **Spend** | **By person** | Who is spending, most first | | | **By tier** | Which tiers carry the bill | | | **Over time** | Daily spend for the window | | | **By person, weekly** | Whose spend is moving | | | **By tier, weekly** | Whether the tier mix is drifting | | | **By tag** | What each business unit or project is costing | | **Savings** | **By tier** | What each tier saved against the model it's measured against | | | **By person** | Who the routing is saving the most for | | | **Over time** | Whether the saving is holding up as the traffic changes | | **Usage** | **Who uses which tier** | Which people are on the dearer tiers | | | **Caching by prompt size** | Whether long prompts are being cached or re-sent in full | | | **Response time by tier** | How long each tier takes to start answering, and to finish | | | **Business unit by tier** | Which team is on which tier | | | **What Auto chose** | Which tier served the requests that arrived as Auto | When you open Cost Reporting from the sidebar with no report in the address, it opens on **Spend › By person**. ### Opening a Report from Overview The **Break this down** buttons on Overview, such as **Spend by tier** or **Savings by tier**, open Cost Reporting on the matching starting point over the last 30 days. Some Insights findings do the same: their **Open Cost Reporting** button opens **By person, weekly**. From there you can change anything. See [Overview](/dispatch/use-dispatch/overview.md) and [Insights](/dispatch/cost-and-insights/insights.md). ## Building a Report Under the starting points, the report reads as a sentence, and each underlined word is a choice: > Show **Spend, Requests, Tokens** **by key owner** then by **tier** over **each week** where tier is **…** {% stepper %} {% step %} **Choose the figures** Click the first blank to open **Figures** and tick as many as you need. A report always keeps at least one. {% endstep %} {% step %} **Break it down** Choose a grouping in **by …**, and optionally a second in **then by …**. Choose **not broken down** for a single total. {% endstep %} {% step %} **Choose a time breakdown** Leave **over the whole period** for one row per group, or pick **each hour**, **each day**, **each week** or **each month** for a series. {% endstep %} {% step %} **Set the Period** Use **Period** in the page header: **Last 7 days**, **Last 14 days**, **Last 30 days** (the default) or **Last 90 days**. There's no custom date range. {% endstep %} {% endstepper %} ### Figures | Figure | What it is | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Spend** | What the traffic cost. See [About the Dollar Figures](#about-the-dollar-figures) | | **Saved** | **Saved by routing** plus **Saved by Prompt Optimization** | | **Saved by routing** | How much less your tiers cost than the model each tier is measured against | | **Saved by Prompt Optimization** | What Prompt Optimization took off the requests it shortened. See [Insights](/dispatch/cost-and-insights/insights.md#prompt-optimization) | | **Cost on the comparator** | What the same traffic would have cost on the model each tier is measured against | | **Requests** | Number of requests | | **Tokens**, **Tokens sent**, **Tokens received** | Total tokens, input tokens and output tokens | | **Tokens served from cache** | Input tokens served from the prompt cache | | **Cache hit rate** | The share of input tokens served from cache | | **Thinking tokens** | Tokens spent on reasoning | | **Typical response time**, **Slow response time**, **Slowest response time** | How long requests took: typical, slow and slowest | | **Typical time to first token** | How long a typical request took to start answering | | **Typical tokens per second** | How fast a typical answer was produced | ### Groupings | Grouping | Breaks the figures down by | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Tier** | The tier that served each request | | **Key owner** | The person who owns the key | | **What was requested** | What the request named. It matches **Tier** except when a request asked for Auto, so pairing the two shows what Auto chose | | **Tag** | The tags on the key that made the request | | **How the answer ended** | The reason each answer stopped | | **Prompt size** | Size bands of the prompt sent | | Your organization's classifications | Each classification your organization has set up appears by its own name. See [Tags](/dispatch/manage/manage/tags.md) | There's no grouping by model or provider: reports group by tier, which is what your plan is written in. There's no grouping by individual key either. To see spend per key, use [API Keys](/dispatch/use-dispatch/api-keys.md). ### Rules for Combining A report can have up to two groupings, and it can't use the same one twice. Tags and classifications come with extra rules, because a key can carry several tags: * A **Tag** or classification report can be broken down further only by **Tier**, **What was requested** or **Key owner**. * It can report **Spend**, **Saved**, **Saved by routing**, **Cost on the comparator**, **Requests**, **Tokens**, **Tokens sent**, **Tokens received** and **Tokens served from cache**. The other figures, including response times and rates, aren't available beside a tag. * It can't be filtered. * You can use one tag or classification grouping at a time. Choices that don't fit the current report are greyed out rather than hidden, with a note at the bottom of the menu saying why. Picking a tag or classification grouping removes any figures and filters it can't use. {% hint style="warning" %} **Tag rows can add up to more than the total.** A key counts its whole spend under every tag it carries, so a **Tag** report's rows overlap. A classification gives each request at most one value, so its rows divide the window and add up to the whole bill. Each report says which kind it is under the sentence. {% endhint %} ### Rows Without a Name | Row | Meaning | | ---------------------------- | ------------------------------------------------------------------------------------------------ | | **Untagged** | The key was checked and carries no tag | | **Unclassified** | Dispatch couldn't place the request under this classification | | **Deleted tag** | Spend against a tag that has since been deleted | | **Not recorded** | The value wasn't recorded for these requests, for example traffic from before tags were recorded | | **Unattributed** | Traffic with no key owner | | **Not in this organization** | A key owner Dispatch holds no record for | ## Narrowing with Filters Filters are added by clicking, not typing. When the table shows **click a name to narrow**, click any name in a grouping column to add it to the sentence as a filter, such as "where key owner is …". Click a different name in the same column to replace the filter, and click the **×** on the filter to remove it. Tag and classification reports can't be filtered, so their names aren't clickable. ## Reading the Results ### Totals Tiles at the top show the whole report's totals for up to the first four figures, with the first one highlighted. When the report is a ranking by one grouping, a **Largest share** tile names the top row and its share of the first figure. Totals always describe the whole report, never just the page you're on. Rates and response times are measured across the whole window rather than averaged from the rows. ### Table and Charts The panel's title restates the report, such as "Spend by tier". How you can view it depends on its shape: | Report shape | Views | | --------------------------- | ------------------------------------------------------------------------ | | One grouping, whole period | **Table** (the default), **Bars**, **Columns**, **Pie** | | Over time | **Area** (the default), **Line**, **Columns**, with the table underneath | | Two groupings, whole period | Table only | * Charts of a ranking draw the top eight rows. The title says "top 8 of …" when there are more. * **Pie** is unavailable when the first figure is a rate or has a negative value. * The table pins an **All** row with the totals above the other rows, and shows each row's share of the first figure where that makes sense. * Rows are ordered by spend, highest first. * Large counts are shortened, such as 11.1B. Hover any figure for the exact value. * Time periods are labelled in UTC. Dispatch remembers your chosen view in this browser. It isn't part of the report's link. ### Pages Long reports are split into pages. Choose 25, 50 or 100 **Rows per page**, and Dispatch remembers that in this browser. Changing the report goes back to page 1. A report holds at most 5,000 rows. Beyond that the footer says "The report stops at the first 5,000 rows. Narrow it to see the rest." If nothing matches, you'll see **Nothing in this window**. Try a longer **Period** or remove a filter. ## Saving and Bookmarking **The address bar is the saved report.** Every change you make updates the page address, so bookmarking it saves the report and opening the bookmark runs it again with current figures. Dispatch doesn't keep a list of saved reports. The link holds the figures, groupings, time breakdown, **Period** and filters. It doesn't hold the page you're on, rows per page or the chart type, so a colleague who opens it sees the same question in their own preferred view. ## Sharing a Report ### With People Who Can Sign In Use **Copy link** (Dispatch Admins find it under **Share**) to copy the report's address. Anyone who can sign in to Dispatch in your organization can open it. {% hint style="info" %} **A copied link shares the question, not your view of the data.** Whoever opens it sees the report at their own role's scope. If a Dispatch Admin sends a link to a Dispatch User, the User sees the same report for their own keys only. {% endhint %} ### With Anyone (Dispatch Admins) **Share › Share with anyone** creates a read-only link for someone who can't sign in, such as finance, an auditor or a board pack. {% stepper %} {% step %} **Name the link** **Name** is filled in from the report, such as "Spend by tier". It appears at the top of the shared page and in your list of links. Up to 120 characters. {% endstep %} {% step %} **Choose how long it works** Set **Link works for** to **7 days**, **30 days** (the default) or **90 days**. {% endstep %} {% step %} **Create and copy it** Click **Create link**, then copy it. This is the only time the link is shown. If it's lost, turn it off and make another. {% endstep %} {% endstepper %} {% hint style="warning" %} **Anyone with the link sees this report for the whole organization, with live figures, without signing in**, until the link expires or you turn it off. If the report is grouped by **Key owner**, that includes people's names and what they spent. {% endhint %} **What the recipient sees:** a page marked **Shared report, read only**, with your organization's name, the link's name, and "Live figures for the last … days · link expires …". The figures always cover the most recent days of the report's **Period**, so opening the link next week shows next week's figures. They can page through the table, change rows per page, switch chart views and **Download CSV**. They can't change the report or click to narrow it. **When a link stops working:** once a link expires or is turned off, it shows **This report is not available**, with a note to ask whoever sent it for a new link. A link that has had a lot of requests in the last minute shows **This link is busy** with a **Try again** button; the link still works. A link that has been downloaded a lot in the last hour refuses further downloads until later. ### Managing Shared Links The **Share this report** dialog lists your organization's share links under **Links you have shared**. Each row shows: * The link's name. Click it to open the report it shows in Cost Reporting. * When it expires (or, once inactive, when it was made) and how many times it has been viewed * Its status: **Active**, **Expired** or **Turned off** Click **Turn off** on an active link to stop it working straight away. A turned-off link can't be turned back on. ## Exporting **Export** offers two CSV downloads: | Option | What you get | | --------------- | --------------------------------------------------------------------- | | **This page** | The rows on screen, without a total row | | **Full report** | Every row of the report, up to 5,000, with a **Total** row at the end | Figures are raw numbers rather than formatted text, so they're ready to work with in a spreadsheet, and names with accented characters open correctly in Excel. If a full report is longer than 5,000 rows, Dispatch tells you it exported the first rows only. **Export** is unavailable when the report has no rows. Dispatch Users export their own keys' figures only, just as they see on screen. ## About the Dollar Figures Every dollar figure in Cost Reporting is in the same terms as the rest of Dispatch. **Spend** here is the figure Overview calls **Total cost**, and it's the same figure your allowance and the organization's budget are measured against. Savings are measured, not billed: * **Saved by routing** compares what your traffic cost with what the same tokens would have cost on the model each tier is measured against, with the same cache hits. A tier that turned out dearer than its comparison counts as zero rather than a negative saving. * **Saved by Prompt Optimization** is priced request by request, at what the removed tokens would have cost on the model that answered. * On a **Tag** or classification report, **Saved** covers routing only. ## Next Steps | Goal | Documentation | | ------------------------------------------------------- | ----------------------------------------------------------------- | | See the fixed 30-day view and its shortcuts | [Overview](/dispatch/use-dispatch/overview.md) | | Find what's worth fixing, and track Prompt Optimization | [Insights](/dispatch/cost-and-insights/insights.md) | | Tag keys so spend can be grouped by project | [Tags](/dispatch/manage/manage/tags.md) | | Understand the tiers your spend is grouped by | [Models](/dispatch/use-dispatch/models.md) | | See spend per key | [API Keys](/dispatch/use-dispatch/api-keys.md) | | Set the budget these figures count against | [Billing & Budget](/dispatch/manage/manage/billing-and-budget.md) | --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.darcyiq.com/dispatch/cost-and-insights/cost-reporting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.