> ## 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 SQL queries and visualizations. You create a dashboard, query your data with SQL against 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. |
| **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 that returns your data. |
| **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 **Table columns** panel to find column names and data roles.
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 and **Run query** above it. 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).

The right rail supports the editor with three panels.

| Panel | Description |
| - | - |
| **Custom dimensions** | Lists the custom dimensions your project captures, so you can group and filter widgets by business-specific values. Custom metrics and dimensions now cover workflow sessions, from function nodes and agent nodes, also to the agent sessions. |
| **Viewer filters** | Lists the fields you can filter this widget on. Use **Find a field** to search, then select **Add filter to this widget**. A viewer filter shows on this widget only. Promote it to apply the filter across the whole dashboard. |
| **Table columns** | Lists every column in the selected table, with a data role badge of `id`, `time`, `dimension`, or `metric`. Use **Filter columns** to search long column lists. |

#### 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.

#### 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. |

### 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.