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

# Custom dashboards

The **Custom Dashboards** page lets you build project-shared dashboards from governed queries and visualizations. You create a dashboard, query your data with SQL or the visual query builder on the platform tables, and save each visualization as a widget. Every dashboard is shared across the project.

There are no fixed metrics on this page. Each widget shows whatever its query returns, over the project's analytics data: events, sessions, LLM calls, feedback, pipeline results, and [custom tags](https://koreai.mintlify.site/agent-platform/analytics-insights/custom-tags.md). Queries are checked before you save them, and they only see this project's data.

To start from a question, write a query in **Analytics Explorer** → **Query** and select **Add to dashboard**.

Navigation: **Insights** → **Custom Dashboards**

Date range: Set at the top of the dashboard: 24 hours, 7 days, 30 days, or 90 days. Widgets that use the `from` and `to` date tokens follow this range, and all applicable widgets update.

**Filters**: Select **All environments** and **All channels** at the top of the page to narrow the data by deployment environment and channel. Filter selections are reflected in the page URL, so you can bookmark a filtered view or share it with a colleague.

When a project has no dashboards, the page shows **No dashboards yet**. Select **New dashboard** to create your first one.

![Custom Dashboards](https://mintcdn.com/koreai/lXC-Go3bScjrntQx/agent-platform/images/analytics-insights/custom-dashboards.png?fit=max\&auto=format\&n=lXC-Go3bScjrntQx\&q=85\&s=b42873d6d8393bad846f2240cca7f70f)

### Dashboard actions

| Action | Description |
| - | - |
| **New dashboard** | Creates an empty dashboard that you name and populate with widgets. |
| **Import** | Loads a dashboard definition from a file. |
| **Export** | Saves the selected dashboard's definition to a file, so you can move it between projects or keep a backup. |
| **Refresh** | Re-runs the queries behind the dashboard's widgets and redraws them with the latest data. |
| **Edit** | Opens the dashboard for changes, such as adding, arranging, or removing widgets. |
| **Time range** | Sets the dashboard date range that date-scoped widgets follow. |
| **Dashboard filter** | A filter that the dashboard's author adds, for example by event type. It applies to every widget that supports it. The list loads more values as you scroll, and search finds any value in the data, including values not yet loaded. Custom dimension filters list values from the dashboard's **Time range**, including a custom range. |
| **Widget actions** | On each widget, view the query behind it (the `</>` icon), or download its data. |

The dashboard picker switches between the project's dashboards. The header shows how many dashboards exist and who created the current one.

> [!NOTE]
>
> Widget titles are typed by whoever builds them. Open the widget's query before you trust its title. If a query returns a field with no values, its table or chart shows an empty column.

### Build a widget

Each visualization on a dashboard is a widget. Select **Add widget** to open the widget editor, which opens as **Untitled widget** and stays open until you save or cancel.

| Control | Description |
| - | - |
| **Query data** | Selects the table and holds the SQL or visual query that returns your data. The visual query builder is available only for tables that support it. Use SQL for every other table. |
| **Preview rows** | Shows the rows the query returned, with result statistics. |
| **Visualize** | Turns the result set into a chart and configures how it displays. |
| **Save widget** | Saves the widget to the dashboard. |
| **Cancel** | Discards the widget and closes the editor. |

To build a widget:

1. Open a dashboard and select **Add widget**.
2. On **Query data**, select a table from the table selector, for example `abl_platform.platform_events`.
3. Write your SQL. Use the **Schema** panel to find column names and types.
4. Select **Run query**. The result panel below the editor reports the rows returned.
5. Open **Preview rows** to confirm the query returns what you expect.
6. Open **Visualize**, choose a chart type, then map your fields to the axes.
7. Select **Save widget**.

#### Query data

The SQL editor sits at the center of the tab, with the table selector, **Schema for AI**, and **Run query** above it. **Schema for AI** copies the selected table's schema in a form an AI assistant can use to draft the query. Queries are scoped by `tenant_id` and `project_id` by default. Use the `from` and `to` date tokens when the widget should follow the dashboard date range. See [Example of Query scoping](#example-of-query-scoping).

![Widget editor with a SQL query and the Schema panel](https://mintcdn.com/koreai/c5_YanW8rc9u7R05/agent-platform/images/analytics-insights/custom-dashboards-widget-query.png?fit=max\&auto=format\&n=c5_YanW8rc9u7R05\&q=85\&s=c6c9fe4981d29e9859184da80f92812f)

The right rail supports the editor with two panels.

| Panel | Description |
| - | - |
| **Schema** | Lists the fields of the selected table. Use the search box to find a field or a custom tag key. Select **Dimensions** to list the table's built-in columns with their types, or **Custom dimensions** to list the custom tag keys stored in it. Custom metrics and dimensions cover workflow sessions, from function nodes and agent nodes, as well as agent sessions. |
| **Filters** | Lists the filters on this widget, with a count. Use **Find a field** to search, then select **Add filter to this widget**. A filter shows on this widget only. Promote it to apply the filter across the whole dashboard. |

[Custom tags](https://koreai.mintlify.site/agent-platform/analytics-insights/custom-tags.md) live in the `custom_dimensions` column, a map of string keys. Read one in SQL as `custom_dimensions['key']`.

#### Label dimensions in a visual query

For tables that support the visual query builder, such as output item tables, give each grouped dimension a readable label so dashboard users don't see raw field names. For example, label the dimension `dim_pnr` as **Booking reference**.

| Item | Behavior |
| - | - |
| **Where to set it** | In the **Summarize** stage, enter a label beside each grouped dimension. The source field stays visible next to its label. |
| **Where it appears** | The label replaces the field name as the column header in preview rows, table widgets, charts, and exported data. |
| **Blank label** | The column keeps the original field name. |
| **Underlying field** | The label changes only the displayed name. Grouping and filtering still use the source field. |

#### Result panel

After you run a query, the panel below the editor holds the result. Switch between **Preview rows** and **Visualization** without leaving the result, so you can check the data and the chart against each other.

The result reports five statistics.

| Statistic | Description |
| - | - |
| **Rows** | Number of rows the query returned. |
| **Columns** | Number of columns in the result set. |
| **Runtime** | Time the query took to execute, in milliseconds. |
| **Row cap** | Maximum rows a single fetch returns, for example `1,000 max`. Table widgets page through results beyond this cap. |
| **Range** | Date range the query ran against, for example `Last 7 days`. |

Below the statistics, a chip for each column shows the data role the platform assigned it, for example `timestamp: time` and `rows: metric`. These roles determine which columns are available to each axis in **Visualize**.

**Preview rows** displays the result as a table, one column per field in the result set. Columns from a visual query show their dimension labels.

![Result panel with statistics, data role chips, and preview rows](https://mintcdn.com/koreai/c5_YanW8rc9u7R05/agent-platform/images/analytics-insights/custom-dashboards-widget-result.png?fit=max\&auto=format\&n=c5_YanW8rc9u7R05\&q=85\&s=21282abc4cdfebb3e55caeeaccff40e2)

#### Visualize

**Visualize** builds the chart from the result set. A status badge reads **Ready** when the current mapping produces a valid chart. Four tabs configure the visualization.

| Tab | Settings |
| - | - |
| **Charts** | Selects the chart type: **Line**, **Area**, **Bar**, **Combo**, or **Table**. Select **More charts** for additional types, such as pie, number, KPI, gauge, funnel, waterfall, and pivot. **Table** widgets page through large result sets, so high-volume data isn't truncated at the first 1,000 rows. |
| **Fields** | Maps result columns to the chart. Set the **X-axis** column, then add one or more **Y-axis series**. Select **Add field** to plot another series, or the delete icon to remove one. |
| **Display** | Sets **Value format** and **Secondary Y axis** behavior, for example **Auto (split mixed scales)** when series use different scales. A **Current mapping** card shows the active X-axis and Y-axis series. |
| **Axes** | Sets the **X-axis label** and **Y-axis label**. Labels default to the mapped column names, or to the dimension labels from a visual query. |

![Visualization with the Charts tab and a line chart marked Ready](https://mintcdn.com/koreai/c5_YanW8rc9u7R05/agent-platform/images/analytics-insights/custom-dashboards-widget-visualize.png?fit=max\&auto=format\&n=c5_YanW8rc9u7R05\&q=85\&s=2fdbe92f5c6f8a73f1ff19494deb9cb9)

### Widget API details

Each widget's data is also available through the widget data API, so you can pull the same numbers into your own reports or scripts. The **API details** dialog shows the exact request the dashboard runs for the widget, with the dashboard's current date range and active filters already applied.

| Item | Description |
| - | - |
| **Method** | The HTTP method of the request. The request uses **POST** when filters apply to the widget, so the filter values travel in the request body. |
| **URL** | The full request URL for the widget. |
| **cURL** | Ready-to-run cURL commands that reproduce the request, including the date range and filters. Copy a command to test the request outside Studio. |
| **Filters** | A table of every filter that reaches the widget, from the widget itself and from the dashboard. For each filter, it shows the API field the filter targets, the operation, the value, and whether the filter applies. |

Use the **Filters** table to check why a widget shows different numbers from the rest of the dashboard. A filter that doesn't apply to the widget's table appears in the list but doesn't change the result.

### Multi-select filters

A dashboard filter can accept one value or several. When you switch a filter to multi-select, the platform updates the SQL of every widget that uses the filter's token, so the widget matches any of the selected values.

| Filter type | SQL condition | Behavior |
| - | - | - |
| Single value | `= {token}` | Matches the one selected value. |
| Multi-select | `IN ({token:Array(String)})` | Matches any of the selected values. The platform rewrites `= {token}` to this form when you switch the filter to multi-select. |

If a single-value token receives more than one value, the widget stops filtering on that field rather than silently using only the first value. Switch the filter to multi-select to filter on several values.

### Example of query scoping

The platform scopes queries to the current tenant and project by default. Let us consider `abl_platform.platform_events` as the query table. Use the date tokens when a widget should follow the dashboard date range.

| Token | Description |
| - | - |
| `{tenantId:String}` | Scopes the query to the current tenant. |
| `{projectId:String}` | Scopes the query to the current project. |
| `{from:DateTime64(3)}` | Start of the dashboard date range. |
| `{to:DateTime64(3)}` | End of the dashboard date range. |

The following query counts events over time and follows the dashboard date range:

```sql theme={null}
SELECT
  timestamp,
  count() AS rows
FROM abl_platform.platform_events
WHERE tenant_id = {tenantId:String}
  AND project_id = {projectId:String}
  AND timestamp >= {from:DateTime64(3)}
  AND timestamp <= {to:DateTime64(3)}
GROUP BY timestamp
ORDER BY timestamp DESC
LIMIT 100
```


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