> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Usage Analytics

> Monitor LLM token consumption across dashboards, execution lists, and workflow run details so you can find high-usage workflows, models, agents, and runs.

Token usage analytics help you understand how your workflows consume LLM capacity over time. Use these views to compare usage across a selected date range, find the workflows and agents that drive consumption, and open high-usage runs for a closer look.

<CardGroup cols={2}>
  <Card title="Track consumption" icon="coins">
    Review total, input, output, and cached input tokens for the date range you choose.
  </Card>

  <Card title="Find usage drivers" icon="chart-bar">
    Break token usage down by model, workflow, step, or agent depending on the dashboard you are viewing.
  </Card>

  <Card title="Investigate runs" icon="magnifying-glass-chart">
    Open high-usage executions from dashboards or lists to inspect run-level and step-level token counts.
  </Card>

  <Card title="Compare periods" icon="arrow-trend-up">
    Use previous-period context to see whether token consumption is rising or falling for the same length of time.
  </Card>
</CardGroup>

## Overview

Token usage analytics are available in the places where you monitor workflow activity:

* The **Project Dashboard** shows project-wide LLM usage across all workflows in the project.
* A **Workflow Dashboard** narrows the same kind of analysis to one workflow.
* The **Executions** list helps you sort runs by token usage.
* **Workflow run details** show the token totals behind a specific run and its steps.

Start with the Project Dashboard when you want to understand overall consumption. Move to a workflow, execution, or step when you need to explain a spike or optimize a specific automation.

## Where token usage appears

### Project Dashboard

The Project Dashboard is the best starting point for project-wide LLM usage. It aggregates token usage across the selected date range and includes:

* **Total Tokens**: all provider-reported LLM tokens used by the project during the selected period.
* **Input Tokens**: tokens sent to LLMs as prompts, instructions, context, and tool-related input.
* **Output Tokens**: tokens generated by LLMs in responses.
* **Cached Input**: the portion of input tokens served from cache when cache data is available. This is a subset of Input Tokens, not an additional amount on top of them.
* **LLM Calls**: the number of LLM requests represented in the selected period.
* **Previous-period comparisons**: context for how the selected period compares with the immediately preceding period of the same length.
* **Token trends**: usage over time based on the selected date range and grouping.
* **Token Usage Breakdown**: usage grouped by **Model**, **Workflow**, or **Agent**.
* **Heaviest Executions**: a leaderboard of runs with the highest total token usage in the selected period.

Use the Project Dashboard to answer questions like:

* Which workflows are responsible for most token usage this week?
* Did usage rise compared with the previous period?
* Are specific models or agents driving the increase?
* Which executions should I inspect first?

### Workflow Dashboard

A Workflow Dashboard focuses token analytics on one workflow. Use it after you identify a workflow that needs closer review from the Project Dashboard.

Workflow-scoped analytics include token KPI cards, token trends for the selected date range, and breakdowns by **Model**, **Step**, and **Agent**. This helps you distinguish whether usage comes from a specific model choice, a step in the workflow, or an agent assigned to the workflow.

### Executions list

The Executions list includes a sortable **Tokens** column. The column shows output token usage for each run, which makes it useful for finding runs that produced unusually large LLM responses.

Sort by **Tokens** when you want to move from dashboard-level trends to the specific runs behind them.

### Workflow run details

Workflow run details show token usage for a single execution. The run summary includes output token usage, with expandable details for:

* **Input Tokens**
* **Cached Input**
* **Output Tokens**
* **Total Tokens**
* **LLM Calls**

When step-level token data is available, individual steps also show output token counts. Use these counts to identify which part of the run contributed most to the total.

## Choose a date range

Dashboard analytics follow the selected **Date Range**. Available presets include:

* **Today**
* **Last 7 Days**
* **Last 30 Days**
* **Last 90 Days**
* **This Month**

On the Project Dashboard, use **Group By** to control how trend charts bucket the selected range:

* **Day** for daily changes and short ranges.
* **Week** for medium-term usage patterns.
* **Month** for longer ranges and month-to-month review.

<Note>
  Selecting **Last 7 Days** from the Date Range control uses the same date window as the default Last 7 Days dashboard view. This keeps analytics consistent when you compare initial dashboard data with the same preset selected later.
</Note>

## Understand token metrics

| Metric            | What it means                                                                                                                                   | How to use it                                                                                  |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Total Tokens**  | The combined token usage reported for LLM calls in the selected scope.                                                                          | Use it as the headline consumption number for a project, workflow, model, agent, step, or run. |
| **Input Tokens**  | Tokens sent to LLMs as instructions, context, and prompts.                                                                                      | Watch for large context windows or workflows that send more information than needed.           |
| **Output Tokens** | Tokens generated by LLMs in responses.                                                                                                          | Use it to find runs or steps where agents produced long answers, summaries, or code changes.   |
| **Cached Input**  | The portion of Input Tokens served from cache when cache data is available. It is a subset of Input Tokens, not an amount added on top of them. | Compare with Input Tokens to understand how often repeated context is reused.                  |
| **LLM Calls**     | The number of LLM requests included in the selected scope.                                                                                      | Use it to distinguish frequent small calls from fewer large calls.                             |

Model breakdowns can show **System** and **Custom** labels. **System** indicates models provided by Overcut defaults or platform configuration. **Custom** indicates models your workspace configured for its own use.

## Break down token usage

Use the **Token Usage Breakdown** panel to identify what contributes most to consumption.

### By Model

Group by **Model** to compare token usage across LLM models. This view is useful when you want to confirm whether a high-capacity model is responsible for a spike or whether usage is spread across several models.

When model rows include **System** or **Custom** labels, use them to distinguish Overcut-provided model options from models configured by your workspace.

### By Workflow

Group by **Workflow** on the Project Dashboard to see which workflows use the most tokens across the selected date range. Start here when you are reviewing project-level usage or looking for candidates to optimize.

### By Agent

Group by **Agent** to understand which agent roles are associated with the most token usage. This can highlight agents that need tighter instructions, narrower context, or a workflow design review.

### By Step

Use the Workflow Dashboard to break a single workflow down by **Step**. This is the most direct way to find where token-heavy work happens inside one automation.

## Investigate high-usage runs

Use this workflow when a dashboard shows unexpected token usage:

<Steps>
  <Step title="Choose the right date range">
    Select the preset that matches the period you want to review. Use **Group By** on the Project Dashboard when you need a daily, weekly, or monthly trend.
  </Step>

  <Step title="Review Project Dashboard KPIs">
    Compare **Total Tokens**, **Input Tokens**, **Output Tokens**, **Cached Input**, and **LLM Calls** with the previous period.
  </Step>

  <Step title="Find the main driver">
    Use **Token Usage Breakdown** to group by **Model**, **Workflow**, or **Agent**. Sort your attention toward rows with the highest **Total** values.
  </Step>

  <Step title="Open a heavy execution">
    Use **Heaviest Executions** or sort the Executions list by **Tokens** to open a run that contributed to the spike.
  </Step>

  <Step title="Inspect run and step details">
    Expand token details in the run summary, then review step output token counts to identify the part of the run that produced the most usage.
  </Step>
</Steps>

<Tip>
  If output tokens are high, review the agent's response requirements and any steps that ask for long summaries or generated code. If input tokens are high, review the amount of context the workflow sends into the agent.
</Tip>

## Related documentation

* [Workflows](/docs/workflows/workflows): Understand workflow structure, triggers, actions, and monitoring.
* [Workflow Execution Control](/docs/workflows/workflow-execution-control): Learn how Overcut manages queued and running workflows.
* [LLM Models](/docs/reference/llm-models): Review model configuration and defaults.
* [Workflow Builder](/docs/how-to/workflow-builder): Configure workflow metadata, steps, and model settings.