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

# Add dashboard panels (API)

> How to design your Dashboard with custom Panels.

You can add Panels in the user interface or using Python API. This pages describes the Python API. Check how to [add panels in the UI](dashboard_add_panels_ui).

## Dashboard Management

<Check>
  Dashboards as code are available in Evidently OSS, Cloud, Enterprise.
</Check>

<Tip>
  You must first connect to [Evidently Cloud](/docs/setup/cloud) and [create a Project](/docs/platform/projects_manage).
</Tip>

**Adding Tabs**. To add a new Tab:

```python theme={null}
project.dashboard.add_tab("Another Tab")
```

You can also create a new Tab while adding a Panel as shown below. If the destination Tab doesn't exist, it will be created. If it does, the Panel will be added below existing ones in that Tab.

**Deleting Tabs**. To delete a Tab:

```python theme={null}
project.dashboard.delete_tab("Another Tab")
```

**Deleting Panels**. To delete a specific Panel:

```python theme={null}
project.dashboard.delete_panel("Dashboard title", "My new tab")
```

(First list the Panel name, then the Tab name).

**\[DANGER]. Delete Dashboard**. To delete all Tabs and Panels on the Dashboard:

```python theme={null}
project.dashboard.clear_dashboard()
```

Note: This does **not** delete the underlying Reports or dataset; it only clears the Panels.

## Adding Panels

Imports:

```
from evidently.sdk.models import PanelMetric
from evidently.sdk.panels import DashboardPanelPlot
```

You can add multiple Panels at once: they will appear in the listed order.

### Text

Text-only panels are perfect for titles.

**Add a text panel**. Add a new text panel to the specified Tab.

```python theme={null}
project.dashboard.add_panel(
    DashboardPanelPlot(
        title="Dashboard title",
        size="full", 
        values=[], #leave empty
        plot_params={"plot_type": "text"},
    ),
    tab="My new tab", #will create a Tab if there is no Tab with this name
)
```

### Counters

Counter panels show a value with optional supporting text.

<CardGroup cols={2}>
  <Card title="Text counter" img="https://mintcdn.com/evi/kUFpUleR1WVLUcMs/images/dashboard/panel_counter_example-min.png?fit=max&auto=format&n=kUFpUleR1WVLUcMs&q=85&s=2f6aaca19242c5a8d011b4222faa1b56" width="1912" height="566" data-path="images/dashboard/panel_counter_example-min.png">
    Shows the specified value(s) and optional text.
  </Card>

  <Card title="Pie chart" img="https://mintcdn.com/evi/kUFpUleR1WVLUcMs/images/dashboard/panel_pie_chart.png?fit=max&auto=format&n=kUFpUleR1WVLUcMs&q=85&s=22a28c93ad991cfcc3a37190df74f31f" width="1298" height="838" data-path="images/dashboard/panel_pie_chart.png">
    Shows the specified value(s) in a pie chart.
  </Card>
</CardGroup>

**Add Counters**. To add panels for the `RowCount` metric with different aggregations:

```python theme={null}
# Sum
project.dashboard.add_panel(
    DashboardPanelPlot(
        title="Row count",
        subtitle="Total number of evaluations over time.",
        size="half",
        values=[PanelMetric(legend="Row count", metric="RowCount")],
        plot_params={"plot_type": "counter", "aggregation": "sum"},
    ),
    tab="My tab",
)

# Average
project.dashboard.add_panel(
    DashboardPanelPlot(
        title="Row count",
        subtitle="Average number of evaluations per Report.",
        size="half",
        values=[PanelMetric(legend="Row count", metric="RowCount")],
        plot_params={"plot_type": "counter", "aggregation": "avg"},
    ),
    tab="My tab",
)

# Last
project.dashboard.add_panel(
    DashboardPanelPlot(
        title="Row count",
        subtitle="Latest number of evaluations.",
        size="half",
        values=[PanelMetric(legend="Row count", metric="RowCount")],
        plot_params={"plot_type": "counter", "aggregation": "last"},
    ),
    tab="My tab",
)
```

**Add pie charts**. You can use the same aggregation params (`sum`, `last`, `avg`).

```python theme={null}
project.dashboard.add_panel(
    DashboardPanelPlot(
        title="Row count",
        subtitle="Total number of evaluations over time.",
        size="half",
        values=[PanelMetric(legend="Row count", metric="RowCount")],
        plot_params={"plot_type": "pie", "aggregation": "sum"},
    ),
    tab="My tab",
)
```

### Plots

These Panels display values as bar or line plots.

<CardGroup cols={3}>
  <Card title="Line chart" img="https://mintcdn.com/evi/kUFpUleR1WVLUcMs/images/dashboard/panel_line_chart.png?fit=max&auto=format&n=kUFpUleR1WVLUcMs&q=85&s=aa5ccf50cb4d2ac84f729e7cbf469521" width="2062" height="948" data-path="images/dashboard/panel_line_chart.png">
    Shows the selected values over time. You can add multiple series to the same chart as multiple lines.
  </Card>

  <Card title="Bar chart (stacked)" img="https://mintcdn.com/evi/kUFpUleR1WVLUcMs/images/dashboard/panel_dist_stacked_2-min.png?fit=max&auto=format&n=kUFpUleR1WVLUcMs&q=85&s=edbf1097529122f7adf2a2af34f3fd83" width="1832" height="900" data-path="images/dashboard/panel_dist_stacked_2-min.png">
    Shows selected values or distributions over time (if stored in each Report). Stacked in a single bar.
  </Card>

  <Card title="Bar chart (grouped)" img="https://mintcdn.com/evi/kUFpUleR1WVLUcMs/images/dashboard/panel_dist_group_2-min.png?fit=max&auto=format&n=kUFpUleR1WVLUcMs&q=85&s=3e2723112efacdc5b1fd5f05221ffd5c" width="1840" height="906" data-path="images/dashboard/panel_dist_group_2-min.png">
    Shows selected values or distributions over time (if stored in each Report). Multiple bars.
  </Card>
</CardGroup>

**Add Plots**. To add time series panels for the `RowCount` metric.

```python theme={null}
# line chart
project.dashboard.add_panel(
             DashboardPanelPlot(
                title="Row count",
                subtitle = "Number of evaluations over time.",
                size="half",
                values=[
                    PanelMetric(
                        legend="Row count",
                        metric="RowCount",
                    ),
                ],
                plot_params={"plot_type": "line"},
            ),
            tab="My tab",
        )
        
# bar chart
project.dashboard.add_panel(
             DashboardPanelPlot(
                title="Row count",
                subtitle = "Number of evaluations over time.",
                size="half",
                values=[
                    PanelMetric(
                        legend="Row count",
                        metric="RowCount",
                    ),
                ],
                plot_params={"plot_type": "bar", "is_stacked": False}, #default False, set as True to get stacked bars
            ),
            tab="My tab",
        )
```

**Multiple values**. A single Panel can show multiple values. For example, this will add multiple lines on a Line chart:

```python theme={null}
project.dashboard.add_panel(
    DashboardPanelPlot(
        title="Text Length",
        subtitle="Text length stats (symbols).",
        size="full",
        values=[
            PanelMetric(legend="max", metric="MaxValue", metric_labels={"column": "length"}),
            PanelMetric(legend="mean", metric="MeanValue", metric_labels={"column": "length"}),
            PanelMetric(legend="min", metric="MinValue", metric_labels={"column": "length"}),
        ]
    )
)
```

### Dashboard Panel options

A summary of all parameters:

| Parameter              | Type   | Required | Default  | Description                                                                               |
| ---------------------- | ------ | -------- | -------- | ----------------------------------------------------------------------------------------- |
| `title`                | `str`  | ❌        | `None`   | Title of the panel.                                                                       |
| `description`          | `str`  | ❌        | `None`   | Optional panel description shown as a subtitle.                                           |
| `size`                 | `str`  | ❌        | `"full"` | Panel size: `"full"` (100% width) or `"half"` (50%).                                      |
| `values`               | `list` | ✅        | —        | List of `PanelMetric` objects to display.                                                 |
| `tab`                  | `str`  | ❌        | `None`   | Dashboard tab name. If not set, defaults to the first tab or creates a new "General" tab. |
| `create_if_not_exists` | `bool` | ❌        | `True`   | If `True`, creates the tab if it doesn't exist. Throws exception if `False`.              |
| `plot_params`          | `dict` | ❌        | `{}`     | Panel visualization settings like `"plot_type"`: `"text"`, `"line"`, `"counter"`.         |

## Configuring Panel values

### Metric

To define which value the Panel displays, you must reference the name of the corresponding Evidently Metric. This metric must be present in the Reports logged to your Project. If the metric isn't present, the Panel will appear empty.

**Dataset-level Metrics**: pass the Metric name directly to `PanelMetric`, e.g., `"RowCount"`.

Example:

```python theme={null}
project.dashboard.add_panel(
             DashboardPanelPlot(
                title="Row count",
                subtitle = "Number of evaluations over time.",
                size="half",
                values=[
                    PanelMetric(
                        legend="Row count",
                        metric="RowCount", ## <- metric name
                    ),
                ],
                plot_params={"plot_type": "line"},
            ),
            tab="My tab",
        )
```

**Presets** (like `TextEvals`, `ClassificationPreset`, `DataDriftPreset`) contain multiple sub-metrics. When logging Reports using a Preset, you must reference the specific **metric** inside it, such as `Accuracy`, `Recall`, etc.

<Info>
  **Need help finding metric names?** See the [All Metrics Reference Table](/metrics/all_metrics) for a full list of Metrics.
</Info>

### Metric labels

Some Metrics require additional context. This applies when the metrics:

* Operate at the column level
* Return multiple values (metric results)
* Have user-defined custom parameters

In these cases, use `metric_labels` to specify what exactly you want to plot.

**Example**. To plot the share of categories inside "Denials" column:

```python theme={null}
project.dashboard.add_panel(
             DashboardPanelPlot(
                title="Denials",
                subtitle = "Number of denials.",
                size="half",
                values=[
                    PanelMetric(
                        legend="""{{label}}""",
                        metric="UniqueValueCount", # <- metric from TextEvals Preset that computes distinct values
                        metric_labels={"column": "denials", #column name
                                       "value_type": "share" #metric result
                                       } 
                    ),
                ],
                plot_params={"plot_type": "bar", "is_stacked": True},
            ),
            tab="My tab",
        )
```

**Column / Descriptor**. When you compute a text descriptor or any metric that operates at the column level, use the `column` label to specify which column or descriptor it refers to.

For example, in a `TextEvals` Report, each text descriptor (e.g., text length, LLM judged "denials", etc.) is treated as a column. These descriptors are summarized with various statistics. To plot one of these values, you need to:

* Choose a summary Metric like `UniqueValueCount`, `MissingValueCount`, `MaxValue`, etc.
* Use the `column` label to point the specific descriptor.

**Example**. To plot the min value from the "Text Length" column:

```python theme={null}
values=[
    PanelMetric(
        legend="Min text length",
        metric="MinValue", # <- metric from TextEvals Preset that computes min value
        metric_labels={
            "column": "TextLength",  # <- target column name 
        }
    )
]
```

**Value type**. Most Evidently Metrics return a single `value`. For example, `Accuracy` returns the corresponding accuracy `value`. So listing just the `Metric` name is enough to specify what exactly you want to plot.

However, some metrics produce more than one metric result, like:

* `CategoryCount`: returns both `share` and `count`
* `MAE`: returns both `mean` and `std`

In this case, you must point to which value you want using the `value_type` key, e.g. `{"value_type": "share"}`

```python theme={null}
values = [
    PanelMetric(
        legend="Share",
        metric="DriftedColumnsCount",  # <- metric from Data Drift Preset that returns `count` or `share` of drifting columns
        metric_labels={"value_type": "share"}  # <- plot relative share
    ),
]
```

<Info>
  **How to verify the metric result for a specific metric?**

  * Look up the expected outputs in the [All Metrics Table](/metrics/all_metrics).
  * Or, generate a Report with the target `metric` and inspect its structure via`report.dict()` or `report.json()`.
</Info>

**Metrics with extra parameters**. If a metric has configurable options (like drift method), you must also include those in `metric_labels`.

### `PanelMetric` options

A summary of all parameters:

| Parameter       | Type   | Required | Default | Description                                                                      |
| --------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------- |
| `legend`        | `str`  | ❌        | `None`  | Legend name in the panel. If `None`, one is auto-generated.                      |
| `tags`          | `list` | ❌        | `[]`    | Optional tags to select values only from a subset of Reports in the Project.     |
| `metadata`      | `dict` | ❌        | `{}`    | Optional metadata to select values only from a subset of Reports in the Project. |
| `metric`        | `str`  | ✅        | —       | Metric name (e.g., `"RowCount"`).                                                |
| `metric_labels` | `dict` | ❌        | `{}`    | Parameters like `column` names (applies to descriptors too) or `value_type`.     |