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

# Build charts

> Plot metrics with time series, top list, and big number charts, export and move charts between dashboards, and add Markdown notes for context.

Charts are the contents of a dashboard. Start from a preset that covers a common metric, or build your own from a SQL measure.

To add context alongside your charts, such as what a dashboard tracks or how to read it, [add a note](#add-notes).

> [!NOTE]
>
> Custom charts are only available on [Pro and Enterprise plans](https://docs.braintrust.dev/plans-and-limits.md#plans).

## Create a chart

On a dashboard you created, click  **Chart** to open the chart editor. To change an existing chart, click the  icon on the chart itself.

Where [SQL charts](https://docs.braintrust.dev/observe/dashboards/sql-charts.md) are available, **Chart** opens a new SQL chart on dashboards that aggregate logs. To use the structured editor described on this page, click the  caret next to  **Chart** and select **Structured chart**.

Charts can only be added to dashboards you create. To add charts to the built-in **Cost and quality** dashboard, [clone it first](https://docs.braintrust.dev/observe/dashboards/create.md#create-a-dashboard).

## Chart editor options

* **Chart type**: Determines the visualization and which other options are available:
  * ** Time series**: Plot metrics over time as lines or stacked bars. Time series charts help you spot trends, anomalies, and correlations.

    **screenshot**

    ![Time series chart editor](https://mintcdn.com/braintrust/I3hW5vZR-Nv7tlsk/images/observe/chart-time-series.png?fit=max\&auto=format\&n=I3hW5vZR-Nv7tlsk\&q=85\&s=82915fbe3f9b0897a093fde44bb5a737)
  * ** Top list**: Rank groups by a metric over the selected timeframe. Order by value or alphabetically, ascending or descending.

    **screenshot**

    ![Top list chart editor](https://mintcdn.com/braintrust/I3hW5vZR-Nv7tlsk/images/observe/chart-top-list.png?fit=max\&auto=format\&n=I3hW5vZR-Nv7tlsk\&q=85\&s=ba71f9ec05b123ecbf0538c9f05f40ab)
  * ** Big number**: Display a single aggregate value as one large number. Useful for highlighting key metrics like total requests or average score.

    **screenshot**

    ![Big number chart editor](https://mintcdn.com/braintrust/I3hW5vZR-Nv7tlsk/images/observe/chart-big-number.png?fit=max\&auto=format\&n=I3hW5vZR-Nv7tlsk\&q=85\&s=882b74716143fec8fef8df033ea61b4b)
* **Presets**: Start from a built-in chart covering common metrics like request count, latency, token usage, and scores. Select the **Presets** tab to pick a preset.

  **screenshot**

  ![Presets tab in the chart editor](https://mintcdn.com/braintrust/I3hW5vZR-Nv7tlsk/images/observe/chart-presets.png?fit=max\&auto=format\&n=I3hW5vZR-Nv7tlsk\&q=85\&s=9f4960b8fb11df8bcedcc82c96af64dd)

  > [!NOTE]
  >
  > Some preset charts (Spans, Latency, Total LLM cost, Token count, and Time to first token) automatically exclude internal scorer spans generated by online scoring automations such as [Topics](https://docs.braintrust.dev/observe/topics.md) and [online scorers](https://docs.braintrust.dev/evaluate/score-online.md). This ensures the metrics reflect actual production traffic rather than scoring overhead. Custom charts include all spans by default. Add a `span_attributes.purpose is null or span_attributes.purpose != 'scorer'` filter to replicate the same behavior.
* **Title**: A label displayed above the chart.
* **Measures**: What to plot. Select a [SQL expression](https://docs.braintrust.dev/reference/sql/query-structure.md#group-by-for-aggregations) and aggregator (sum, avg, min, max, count, count distinct, or percentile), or select `</>` to enter a full SQL aggregate expression such as `avg(latency) / count_distinct(user_id)` or `100 * sum(errors) / count(id)`. Invalid expressions display a validation error on hover. Built-in measure types are also available for [aggregate scores](https://docs.braintrust.dev/admin/projects.md#create-aggregate-scores) and cost.
* **Filters**: Narrow results by span or trace conditions:
  * **Span filter**: Limits which individual spans contribute to the measure. Click **Span filter** to add one.
  * **Trace filter**: Narrows results to traces where any span satisfies the [filter conditions](https://docs.braintrust.dev/reference/sql/query-structure.md#where), useful for filtering by root-span metadata such as `metadata.email`. To add one, open the more options menu () next to **Span filter** and select **Trace filter**. Existing trace conditions appear under a **Trace filters (optional)** subsection.
* **Group by**: Split the chart into separate series by a SQL dimension, such as `metadata.model`. Available for time series and top list charts.
* **Options**: Controls visualization-specific settings:
  * **Unit type**: Choose how values appear in chart axes, tooltips, and legends:
    * **Duration**: Seconds (e.g., "1.5s", "0.3s").
    * **Cost**: US dollars (e.g., "$0.05", "$1.23").
    * **Count**: Generic countable things (e.g., "1,234", "5.5").
    * **Percent**: Percentages (e.g., "75%", "100%").
    * **Bytes**: Binary byte units using base-1024 (e.g., "1 KB", "2 GB", "500 B").
  * **Visualization**: Visualize as lines or bars. Available for time series charts only.
  * **Target time interval**: Set the time bucket size for time series charts. Choose **Auto** to let Braintrust pick bucket sizes based on the visible time range, or select **Week**, **Day**, or **Hour** to override the automatic choice. The selected interval is a target, not a guarantee. If it would produce buckets that are too small or too large to read at the visible time range, Braintrust falls back to the nearest readable bucket size. Available for time series charts only.

    By default, buckets are assigned by `created` (ingestion time). To use `metrics.start` (event start time) instead, which is useful for projects that batch-ingest historical spans, see [Configure Monitor chart time dimension](https://docs.braintrust.dev/admin/projects.md#configure-monitor-chart-time-dimension).
  * **Sort**: Sort by value or name, ascending or descending. Available for top list charts only.
  * **Markers**: Highlight values or ranges by severity. Available for time series, top list, and big number charts. See [Add markers](#add-markers).

## Add markers

Markers highlight threshold values and ranges on a chart, such as a latency target or an error rate limit. Each marker pairs a condition with a severity, and the chart shows matching values in that severity's color:

* **Time series**: A horizontal line marks each marker value. Markers other than **Equal to** also shade the matching region. A dashed line means the value itself doesn't match the condition. Each line is labeled with its value or range, or with a custom label.
* **Top list**: A vertical line marks each marker value, and bars whose value matches a marker take its color.
* **Big number**: The background takes the marker's color when the value matches.

To add a marker:

1. In the chart editor's **Options**, click  **Marker**.
2. Under **Bounds**, select a condition: **Greater than**, **Greater than or equal to**, **Between**, **Equal to**, **Less than**, or **Less than or equal to**. Enter a value, or two values for **Between**.
3. Select a **Severity**: **Info**, **Optimal**, **Warning**, or **Error**.
4. For a time series chart, enter a label in **Custom label (optional)** to replace the default value label.

Enter values in the chart's unit type. For **Percent**, enter `75` for 75%.

On top list and big number charts, when a value matches more than one marker, the first marker in the list sets its color. Time series charts shade every marker's region, layered where they overlap. Drag the  handle to reorder markers, and click  to remove one.

Markers aren't available for donut or table charts.

## Performance warnings

As you configure a chart, Braintrust flags settings that are likely to make it slow. A  warning appears next to the affected measure or filter, with an explanation of what to change. On a measure, the explanation also appears when you hover over the input. Group-by fields are checked as a set rather than individually.

Saving a custom chart that still has warnings prompts you to confirm with **Save anyway**. Preset charts save without the prompt.

## Build charts with Loop

In the chart editor header, click  **Loop** to build or refine a chart with [Loop](https://docs.braintrust.dev/loop.md). The chart is added to the conversation's context automatically. When you send a message, Loop receives the chart's configuration, including unsaved edits, and the editor's selected time range. Remove the chart's context badge to stop including its configuration in your messages.

Example prompts:

* "List the top 5 models by error rate over the last 7 days."
* "Show error rate over time for Claude models."
* "Display average latency grouped by user."
* "Chart token usage trends for the past month."

You can also [save a Loop query result as a dashboard chart](https://docs.braintrust.dev/observe/filter.md#ask-questions-with-loop) without leaving Logs.

## Add notes

Notes are Markdown cards that sit alongside charts on a dashboard. Use them to explain what a dashboard tracks, link to runbooks, or annotate a group of charts.

> [!NOTE]
>
> Notes are only available on [Pro and Enterprise plans](https://docs.braintrust.dev/plans-and-limits.md#plans).

Requires data plane v2.16.0+ (Self-hosted customers must upgrade to use this feature.)

To add a note to a dashboard you created:

1. Click the  caret next to  **Chart** and select  **Note**.
2. Write the note in the Markdown text area. A live preview appears next to it.
3. Click **Save as new**, or press `Cmd+Enter` (macOS) or `Ctrl+Enter` (Windows and Linux).

Notes have no title bar. To change a note, hover over it and click the  icon.

Notes support the same options as charts for dragging, duplicating, deleting, copying, and grouping into sections. **Export to dashboard**, **Export data**, and **Open in Query** aren't available for notes. To add a note to another dashboard, select **Copy config** and paste it there. A note's link opens in a read-only view instead of fullscreen.

## Move and copy charts

Hover over a chart and click the more options menu () to access the following options:

* **Export to dashboard**: Copy the chart to a different dashboard in the same project or another project. In the dialog that opens, pick the destination project and dashboard, then click **Add chart**. The built-in **Cost and quality** dashboard can't be a destination.
* **Copy link**: Copy a shareable link to the chart. The link opens the chart in fullscreen mode.
* **Copy config**: Copy the chart's or note's configuration to your clipboard. Paste it on any dashboard to add it there.
* **Open in Query**: Open the chart's underlying query on the Query page for further exploration.

To add an identical copy of a chart to the dashboard you are on, hover over it, open the more options menu (), and select ** Duplicate**.

## Organize charts into sections

Group related charts into named **sections** to keep a long dashboard readable. Sections can be renamed, reordered, collapsed, duplicated, and deleted on dashboards you create.

> [!NOTE]
>
> Sections are only available on [Pro and Enterprise plans](https://docs.braintrust.dev/plans-and-limits.md#plans).

Requires data plane v2.13.0+ (Self-hosted customers must upgrade to use this feature.)

You can create a section in two ways:

* Select one or more charts, then click  **Section** in the selection bar to group them.
* Click the  caret next to  **Chart** and select **Section** to start an empty section, then drag charts onto it afterward. An empty section shows only its header row until it contains a chart.

Name the section in the dialog to create it.

Once a section exists, you can:

* **Rename it**: Click the section title and edit it in place.
* **Reorder it**: Drag the  handle in the section header to move the section and its charts.
* **Collapse or expand it**: Click anywhere on the section header, or the  button, to hide or show its charts. Braintrust remembers each section's collapsed state in your browser, so it persists across page reloads. Duplicating a section keeps its collapsed state. A section with no charts stays collapsed and has no  button.
* **Duplicate or delete it**: Hover over the section header, open the  **Section options** menu, and choose ** Duplicate** or ** Delete**. Deleting a section leaves its charts on the dashboard.

## Export chart data

Hover over a chart, open the more options menu (), and select ** Export data** to download the chart's underlying data:

* **JSON**: Download the data as a JSON file.
* **CSV**: Download the data as a CSV file.

Table charts load rows in pages of 100. When more rows remain, the **Export data** menu shows the count of rows loaded so far and the export covers only those rows. Click **Load 100 more rows** to fetch additional pages before exporting.

## Delete charts

Hover over a chart, open the more options menu (), and select ** Delete** to remove it from the dashboard. Charts can only be deleted from dashboards you create, not from the built-in **Cost and quality** dashboard.

## Next steps

* [Filter and group data](https://docs.braintrust.dev/observe/dashboards.md#filter-and-group-data) across every chart on a dashboard.
* [Copy a dashboard to another project](https://docs.braintrust.dev/observe/dashboards/create.md#copy-a-dashboard-to-another-project) once you have a set of charts worth reusing.
* Read the [SQL reference](https://docs.braintrust.dev/reference/sql.md) to write more advanced measures and filters.
* [Score online](https://docs.braintrust.dev/evaluate/score-online.md) to add quality metrics you can chart.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.