Dashboards

Open Dashboards

Dashboards is a product in the product switcher at the top left of LangWatch. On LangWatch Cloud, no setup is needed. On a self-hosted install, Dashboards stays off until an operator turns it on in Ops > Feature flags. Turn on release_dashboards to open Dashboards, and release_lwql_workbench to build and edit widgets on a dashboard.

Your first dashboard

Opening Dashboards opens your dashboard called “My dashboard”, and it starts in your pinned dashboards. If you have no such dashboard yet, LangWatch makes one for you. It starts at the scope Only me, so only you see it. You can change its scope like any other dashboard’s (see Who can see a dashboard). The sidebar lists, in order:

Your dashboards: your “My dashboard” first, then the project’s other dashboards by name. The + next to the heading makes a blank dashboard at once and opens it.
Pinned: the dashboards you pinned, in your own order. Pins are yours alone. The menu of a pinned dashboard has Move up and Move down.
From your organisation: the heading reads “From” and your organisation’s name. It lists the dashboards that other projects of your organisation set to Organization, by name, and shows only when there is such a dashboard.
From LangWatch: dashboards LangWatch made for you. Click the heading to fold the group; it stays folded until you click it again.

A dashboard set to Only me has a small lock next to its name, and a dashboard set to Organization has a building. A Project dashboard has no mark. The ⋮ menu of a dashboard offers Pin or Unpin, Rename, Duplicate and Delete. On a dashboard you made it also offers the three scope choices. On a dashboard you cannot edit it offers Pin or Unpin and Duplicate to edit. “My dashboard” cannot be renamed or deleted.

Start from a template

A dashboard without widgets shows the ask bar, suggested questions, and “Or start from a template” with the three From LangWatch dashboards and a View all templates link. The templates library lists every ready template by Grow, Protect, Profit and Trust, with a search box and filters for the category and the agent type. Add to this project on a card creates a new dashboard named after the template (numbered “Agent health 2” and so on if the name is taken), at the scope Project, with the template’s widgets. A template you already added shows Added, linking to its dashboard. When Langy is enabled for your project, Langy opens with the template’s report prompt ready in the composer, unsent. The prompt also asks Langy to check what the dashboard needs that your project has not set up yet, and names the widgets that wait for that data. Without Langy the dashboard is made and no prompt is drafted. A widget whose data is not set up yet says what is missing and links to the page that sets it up, such as evaluations, scenarios or feedback. The Agent health template holds five widgets:

This period
Status today
Needs attention
Top request my agent cannot serve
Conversations resolved per day

A new dashboard is yours like any other: every widget on it can be edited, duplicated, moved, resized or deleted, and your changes do not affect the template.

From LangWatch dashboards

The From LangWatch group in the sidebar holds Release check, “Can I trust my numbers?” and Where my agent breaks. Each is a template shown live over your data and read-only: you cannot move, edit or add anything on it, and LangWatch stores no copy. To change one, open its ⋮ menu in the sidebar and pick Duplicate to edit. That makes your own dashboard, named after the template plus “(copy)”, with the template’s widgets and opens it. The dashboard’s header has no such button.

Period and grain

Every dashboard has a period, from Live (the last hour) up to one year, defaulting to 30 days, and a grain: auto, minute, hour, day or week. A grain is offered only when it fits the period, and a grain that does not fit is greyed out. Every widget on the dashboard reads over that period and grain.

Keep the data fresh

The header has one period control. Its menu has three columns, Range, Grain and Refresh, and ends with Refresh now, which reloads every widget on the dashboard. The Refresh column reloads every widget every minute, every 5 minutes, or never (Off). Pick Live for the last hour, rolling and refreshed every minute. The other refresh choices are greyed out until you pick another range.

Building your own dashboard

On a dashboard, you can rename it from the sidebar menu and add a description. Add a widget opens the picker; I’ll build it myself there opens the widget editor, where you write the widget’s code and its LangWatchQL queries. Move a widget by its drag handle and resize it from its corner. Each widget’s menu offers:

Edit with Langy: asks Langy to change the widget. Only when Langy is available.
Edit code: opens the widget editor on that widget’s code and queries.
Copy widget id and Copy API snippet: copy what the REST API needs to edit the widget.
Set an alert and Send as a report: draft Langy to alert on, or schedule, that widget. Only when Langy is available.
Duplicate: adds a copy of the widget.
Delete: removes the widget.

Every query in a widget has a built-in sources parameter: the trace origins it counts. The widget editor shows it as the first row under Parameters on the Queries tab, one pill per source. Remove a pill to stop counting that origin, or pick one from Add source:

application: your own agent. A trace with no origin set counts here.
simulation, evaluation, sample, coding_agent, ai_tool, gateway, workflow, playground: traces LangWatch itself produces.
langy: your conversations with Langy.
other: any origin not listed above.

A new widget counts application, and a stock widget from the template does too. A widget about Langy’s failed requests adds langy. The preview runs again when you change the sources, and each card names its sources in a quiet line underneath. A query with no source picked returns no rows, and its widget says No sources picked. Sources only apply where the SQL reads the parameter. A query that does not read {dashboard_context_sources:Array(String)} counts every origin, and its card says Sources: all sources. A widget saved before this release keeps its SQL, so it counts every origin until you edit it to read the parameter or add it again from the template.

Who can see a dashboard

Every dashboard has a scope, shown next to its title:

Only me: only you see the dashboard.
Project: everyone in the project sees it. A new dashboard starts here.
Organization: everyone in your organisation sees it, in each of their projects. In each project the dashboard shows that project’s own data, and each member sees what their role lets them see.

Only the member who made a dashboard can change its scope, from the control next to the title or from the dashboard’s ⋮ menu in the sidebar. A project admin cannot. Everyone else sees the scope as a badge. Who can edit or delete a dashboard does not change: that still follows your role’s analytics permissions. LangWatch asks you to confirm a change only when somebody loses the dashboard: when you set a dashboard to Only me that other members pinned, and when you lower a dashboard from Organization. Every other change happens at once, and the note that follows has an Undo. Other members’ pins are kept, and come back if you widen the scope again. The project where a dashboard was made owns it. An Organization dashboard can be edited only in that project. In every other project it is read-only: you cannot add, move, edit or delete a widget, and the header says which project owns the dashboard. To change it, pick Duplicate to edit in the dashboard’s ⋮ menu in the sidebar. That makes your own copy in the project you are in. An Organization dashboard also has a Project control in its header. It names the project whose data you see, and lists the projects of your organisation that you can open. Pick one to open the same dashboard under that project. If you open the address of a dashboard that you may not see, the page says “This dashboard is not available”. The dashboard was deleted, or the member who made it set its scope to Only me. A project API key reads the project’s dashboards except the ones set to Only me. Alerts and scheduled reports do not read a dashboard set to Only me either. An alert or a report on a chart of such a dashboard sends no chart until you widen the dashboard’s scope.

Asking questions

Every dashboard has an ask bar under its header, reading “What do you want to know?”. On a stored dashboard, clicking it opens Add a widget with the cursor in its search. On a From LangWatch dashboard, the bar opens Langy when Langy is available, with the dashboard as context and no question sent yet. The picker lists suggested questions, grouped by the question tree, with a search and filters for the category and the agent type. Picking one adds that question’s widget to the dashboard, below the widgets already there. When Langy is enabled for your project, Langy then opens with the question’s prompt ready in the composer, with the dashboard as context, so you can read it and send it with one click. Without Langy the picker still lists every question, and picking one adds its widget. The pinned Ask Langy footer, and the Ask button next to the search field, send your own question to Langy directly. On a dashboard that already has widgets, the Add a widget box below the widgets and the Add a widget button in the header both open the picker. Every widget has an Ask Langy button when Langy is available; it drafts a prompt with the widget’s name, its queries and the period.

How the data is read

All dashboard data is read with LangWatchQL, LangWatch’s query layer over your traces, evaluations and cost data. A widget query has two settings beside its SQL. sources lists the trace sources {dashboard_context_sources:Array(String)} is bound to (application by default), and a query is kept to them only where its SQL uses that parameter in a condition, such as WHERE Source IN {dashboard_context_sources:Array(String)}. A query that does not use it is not filtered by sources and counts every source, and its card says “all sources”. projects lists the projects the query reads, bound to {dashboard_context_projects:Array(String)}; a query that names none reads its board’s project. A project you cannot read makes that card draw “You can’t read a project this widget uses” without naming it. When the server cut a run’s rows, such as a project shared only from a date, the card shows one (i) line saying so. Rolling back to a release before this one shows multi-project widgets for the board’s project only. A rollback is not supported for this feature.

Build dashboards from your own AI agent

Your coding assistant can build and edit LangWatch dashboards for you, through the LangWatch MCP server.

Connect the MCP server

Connect Claude Code, Cursor, or another MCP-capable assistant to LangWatch first. Follow the LangWatch MCP Server setup guide to add the server and set your API key.

Dashboard tools

Once connected, your agent has these dashboard tools:

list_dashboards: list the project’s dashboards, with the id each widget tool takes.
get_dashboard: read one dashboard by its id.
create_dashboard: create an empty dashboard.
rename_dashboard: change a dashboard’s name.
delete_dashboard: delete a dashboard and its widgets.
list_dashboard_widgets: list the widgets of one dashboard. Pass the dashboardId.
run_query: run one read-only LangWatchQL (LWQL) statement and see the rows it returns. Use this to check a query before it goes into a widget.
add_dashboard_widget: create a custom widget and add it to a dashboard.
update_dashboard_widget: change a widget’s name, code, queries or description. Pass the dashboard id, the widget id, and only the fields to change. Every field you leave out keeps its value.
delete_dashboard_widget: remove a widget from a dashboard.

The old Analytics Reports have their own tools: platform_list_analytics_reports, platform_get_analytics_report, platform_create_analytics_report, platform_rename_analytics_report and platform_delete_analytics_report. The tools that act on an existing report (platform_get_analytics_report, platform_rename_analytics_report and platform_delete_analytics_report) take a reportId. Analytics Reports hold charts, not widgets. A widget has two parts:

code: a TSX source file. It runs sandboxed in the browser and renders the widget’s chart or panel.
queries: up to 8 named LangWatchQL statements the code can read from. Pass them as { "<name>": "<LWQL SQL>" }, or as a list of { name, sql } entries.

Ask your agent to validate each query with run_query before it calls add_dashboard_widget. A query only actually runs once the widget renders inside the sandbox, so catching a mistake in the SQL earlier, with run_query, is faster than catching it on the dashboard. Inside code, a global LW object gives the widget everything it needs:

LW.dashboardContext: the dashboard’s current time window, granularity, timezone and theme.
LW.params: the widget’s own author-declared parameter values.
LW.theme: the dashboard’s current colour theme ("light" or "dark").
LW.query(name, params?): runs one of the widget’s named queries and returns its rows.
LW.useChartQuery(name, params?): the React hook version of LW.query. Gives data, completeness, isLoading, isFetching, isError, error, status, and refetch, and refetches automatically when the dashboard’s time window or granularity changes. Use this instead of LW.query in most widgets.
LW.setHeight(px): resizes the widget’s frame once its content’s height is known.
LW.onDashboardContextChange(callback) / LW.useDashboardContext(): subscribe to, or read, the dashboard’s live context.
LW.useParams(): read the widget’s author-declared parameter values.
LW.error(err): report an error without throwing.
LW.navigate(target, params?): navigate the host to an allowlisted target, such as a trace list or a single trace.

Missing data: the `completeness` report

A query that follows the dashboard’s time window also returns a completeness report next to its rows. POST /api/v1/query returns it too when you pass a timeWindow. Use it so a widget never shows missing data as zero.

completeness: {
  state: "complete" | "partial" | "missing" | "no_traffic";
  unit: string;   // what `total` counts: "traces", "spans", "evaluations"
  total: number;  // rows of that view in the window
  fields: { field: string; label: string; present: number }[];
  buckets?: { start: string; n: number }[];        // ISO start, UTC
  unpriced?: { count: number; models: string[] };
}

state: no_traffic means no rows arrived in the period. missing means a field the query reads is on no row: show a setup step that names the field to send. partial means some rows lack a field, or some cost has no price.
fields: one entry per field the query reads that can be empty, with how many of total rows carry it.
buckets: only when the query follows the dashboard granularity. It lists every bucket in the window, including empty ones at the start and the end, with n: 0. Draw an empty bucket as a gap for a rate, an average or a percentile, never as 0. A count may be 0.
unpriced: only when the query reads cost. count is the rows with at least one span whose model has no price, and models names those models. A cost total with unpriced rows is a lower bound: show it as “$830+”. Traces recorded before LangWatch started tracking this report no unpriced spans, so on older periods the absence of unpriced rows is not proof that every span was priced.

The report is absent when the query does not follow the dashboard’s time window, when it reads a per-minute rollup view, or when it could not be built. Treat an absent report as “unknown”, not as “complete”.

Example prompt

Add a widget to my Agent health dashboard that shows p95 latency by model
for the last 7 days.

Your agent will validate the LWQL with run_query, write the widget’s TSX code against LW.useChartQuery, and call add_dashboard_widget to add it to the dashboard. The same edit works without MCP. Send a PATCH with your project API key and only the fields to change:

curl -X PATCH "https://app.langwatch.ai/api/v1/projects/$PROJECT_ID/analytics/dashboard-widgets/$WIDGET_ID" \
  -H "X-Auth-Token: $LANGWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Errors per day", "code": "<the widget code>"}'

The body takes any of name, code, queries and description. Each query may carry sources, such as ["application", "langy"]; a query sent without it keeps the sources stored under its name, and "sources": null returns it to application. A query renamed without sources has no stored list under its new name, so it counts application; send its sources with the rename to keep them. The answer is the updated widget. Each widget also records where it came from in definition.source: a catalogue template, Langy, the code editor or the API. A widget you create through the API without a source is recorded as api.

Manage dashboards from code

The SDKs, the CLI and the REST API manage the same dashboards and widgets as the app.

import { LangWatch } from "langwatch";

const client = new LangWatch();

const dashboards = await client.dashboards.list();
const dashboard = await client.dashboards.create({ name: "Agent health" });

await client.dashboards.update({
  dashboardId: dashboard.id,
  name: "Agent health (prod)",
});

const widgets = await client.dashboards.listWidgets(dashboard.id);

import langwatch

dashboards = langwatch.dashboards.list()
dashboard = langwatch.dashboards.create(name="Agent health")

langwatch.dashboards.update(dashboard_id=dashboard.id, name="Agent health (prod)")

widgets = langwatch.dashboards.list_widgets(dashboard_id=dashboard.id)

langwatch dashboard list
langwatch dashboard create "Agent health"
langwatch dashboard update <dashboardId> --name "Agent health (prod)"
langwatch dashboard widget list <dashboardId>
langwatch dashboard delete <dashboardId>

curl "https://app.langwatch.ai/api/v1/dashboards" \
  -H "X-Auth-Token: $LANGWATCH_API_KEY"

A widget has its verbs under widget: langwatch dashboard widget list|get|add|update|delete <dashboardId> [<widgetId>], and createWidget, getWidget, updateWidget and deleteWidget in the TypeScript SDK (create_widget, get_widget, update_widget and delete_widget in Python).

The REST API

/api/v1/dashboards serves dashboards and their widgets from API version 2026-10-26. A request pinned to an earlier X-API-Version gets a 404. See API reference > Dashboards. Analytics Reports dashboards are at /api/v1/analytics/reports.

Analytics Reports

The old Analytics Reports are a separate API: client.analyticsReports and langwatch.analytics_reports in the SDKs, langwatch analytics-report list|get|create|update|delete in the CLI, and /api/v1/analytics/reports over REST.

Names that changed

langwatch dashboard now manages the new Dashboards (widgets under langwatch dashboard widget); it used to manage the old Analytics Reports, which are now langwatch analytics-report. The dashboards and dashboard-widget CLI groups, client.boards, langwatch.boards, BoardsFacade and DashboardWidgetsApiService are removed, with no alias: use client.dashboards and langwatch.dashboards.

Get Started

Agent Testing

Observability

Evaluations

Prompt Management

Platform

Examples & Cookbooks

Help

Open Dashboards

Your first dashboard

The sidebar

Start from a template

From LangWatch dashboards

Period and grain

Keep the data fresh

Building your own dashboard

What a widget’s queries count

Who can see a dashboard

Asking questions

How the data is read

Build dashboards from your own AI agent

Connect the MCP server

Dashboard tools

The widget definition format

The LW widget API

Missing data: the `completeness` report

Example prompt

Edit a widget through the REST API

Manage dashboards from code

The REST API

Analytics Reports

Names that changed

​Open Dashboards

​Your first dashboard

​The sidebar

​Start from a template

​From LangWatch dashboards

​Period and grain

​Keep the data fresh

​Building your own dashboard

​What a widget’s queries count

​Who can see a dashboard

​Asking questions

​How the data is read

​Build dashboards from your own AI agent

​Connect the MCP server

​Dashboard tools

​The widget definition format

​The LW widget API

​Missing data: the completeness report

​Example prompt

​Edit a widget through the REST API

​Manage dashboards from code

​The REST API

​Analytics Reports

​Names that changed

Open Dashboards

Your first dashboard

The sidebar

Start from a template

From LangWatch dashboards

Period and grain

Keep the data fresh

Building your own dashboard

What a widget’s queries count

Who can see a dashboard

Asking questions

How the data is read

Build dashboards from your own AI agent

Connect the MCP server

Dashboard tools

The widget definition format

The LW widget API

Missing data: the `completeness` report

Example prompt

Edit a widget through the REST API

Manage dashboards from code

The REST API

Analytics Reports

Names that changed