Implementation:Langfuse Langfuse DashboardService

Knowledge Sources	Langfuse
Domains	Dashboard, Widgets, PostgreSQL
Last Updated	2026-02-14 00:00 GMT

Overview

The DashboardService is a static service class that manages CRUD operations for dashboards and dashboard widgets in Langfuse, using Prisma ORM against PostgreSQL.

Description

The DashboardService class provides a complete set of static methods for managing the dashboard and widget system in Langfuse. Dashboards are customizable views that contain one or more widgets arranged in a grid layout. Widgets represent individual visualizations backed by configurable views, dimensions, metrics, filters, and chart types.

Key capabilities include:

Dashboard management - listDashboards, createDashboard, getDashboard, updateDashboard, updateDashboardDefinition, updateDashboardFilters, deleteDashboard
Widget management - listWidgets, createWidget, getWidget, updateWidget, deleteWidget
Widget copying - copyWidgetToProject duplicates a Langfuse-owned (global) widget into a user's project scope and rewires the dashboard placement atomically within a transaction

The service distinguishes between project-owned and Langfuse-owned entities: dashboards and widgets with a null projectId are global Langfuse-managed defaults, while those with a projectId are project-specific. The owner field in domain objects is derived from this distinction.

Dashboard definitions use a structured schema (DashboardDefinitionSchema) containing an array of widget placements, each with grid position (x, y) and size (x_size, y_size) properties.

Widget deletion includes referential integrity checking -- attempting to delete a widget still referenced in any dashboard definition raises a LangfuseConflictError.

Usage

Use this service when you need to:

List, create, update, or delete dashboards for a project.
Manage dashboard widget definitions and their grid layouts.
Copy a Langfuse-provided default widget into a project to allow customization.
Update dashboard-level filters that apply across all widgets.

Code Reference

Source Location

Repository: Langfuse
File: packages/shared/src/server/services/DashboardService/DashboardService.ts
Lines: 1-473

Signature

export class DashboardService {
  static async listDashboards(props: {
    projectId: string;
    limit?: number;
    page?: number;
    orderBy?: OrderByState;
  }): Promise<DashboardListResponse>;

  static async createDashboard(
    projectId: string,
    name: string,
    description: string,
    userId?: string,
    initialDefinition?: DashboardDefinitionSchema,
  ): Promise<DashboardDomain>;

  static async updateDashboardDefinition(
    dashboardId: string,
    projectId: string,
    definition: DashboardDefinitionSchema,
    userId?: string,
  ): Promise<DashboardDomain>;

  static async updateDashboard(
    dashboardId: string,
    projectId: string,
    name: string,
    description: string,
    userId?: string,
  ): Promise<DashboardDomain>;

  static async updateDashboardFilters(
    dashboardId: string,
    projectId: string,
    filters: singleFilter[],
    userId?: string,
  ): Promise<DashboardDomain>;

  static async getDashboard(
    dashboardId: string,
    projectId: string,
  ): Promise<DashboardDomain | null>;

  static async deleteDashboard(
    dashboardId: string,
    projectId: string,
  ): Promise<void>;

  static async listWidgets(props: {
    projectId: string;
    limit?: number;
    page?: number;
    orderBy?: OrderByState;
  }): Promise<WidgetListResponse>;

  static async createWidget(
    projectId: string,
    input: CreateWidgetInput,
    userId?: string,
  ): Promise<WidgetDomain>;

  static async getWidget(
    widgetId: string,
    projectId: string,
  ): Promise<WidgetDomain | null>;

  static async updateWidget(
    projectId: string,
    widgetId: string,
    input: CreateWidgetInput,
    userId?: string,
  ): Promise<WidgetDomain>;

  static async deleteWidget(
    widgetId: string,
    projectId: string,
  ): Promise<void>;

  static async copyWidgetToProject(props: {
    sourceWidgetId: string;
    projectId: string;
    dashboardId: string;
    placementId: string;
    userId?: string;
  }): Promise<string>;
}

Import

import { DashboardService } from "@langfuse/shared/src/server/services/DashboardService/DashboardService";

I/O Contract

Inputs

Name	Type	Required	Description
projectId	string	Yes	The project ID scoping the dashboard/widget operations
dashboardId	string	Yes (for updates/deletes)	The unique identifier of the dashboard
widgetId	string	Yes (for widget ops)	The unique identifier of the widget
name	string	Yes (for create/update)	Display name for the dashboard or widget
description	string	Yes (for create/update)	Description text for the dashboard or widget
definition	DashboardDefinitionSchema	Yes (for definition update)	Grid layout definition with widget placements
filters	singleFilter[]	Yes (for filter update)	Array of filter conditions applied at dashboard level
input	CreateWidgetInput	Yes (for widget create/update)	Widget configuration including view, dimensions, metrics, filters, chartType, chartConfig
userId	string	No	The ID of the user performing the action, stored for audit trail
limit / page	number	No	Pagination parameters
orderBy	OrderByState	No	Column and direction for sorting

Outputs

Name	Type	Description
DashboardDomain	object	Dashboard domain object with id, name, description, definition, filters, owner, timestamps
DashboardListResponse	object	Contains dashboards array and totalCount for pagination
WidgetDomain	object	Widget domain object with id, name, description, view, dimensions, metrics, filters, chartType, chartConfig, owner
WidgetListResponse	object	Contains widgets array and totalCount for pagination
string	string	New widget ID returned by copyWidgetToProject

Usage Examples

// List all dashboards for a project
const { dashboards, totalCount } = await DashboardService.listDashboards({
  projectId: "proj-123",
  limit: 10,
  page: 1,
});

// Create a new dashboard
const dashboard = await DashboardService.createDashboard(
  "proj-123",
  "LLM Performance",
  "Tracks key LLM metrics",
  "user-1",
);

// Copy a Langfuse default widget into a project
const newWidgetId = await DashboardService.copyWidgetToProject({
  sourceWidgetId: "global-widget-1",
  projectId: "proj-123",
  dashboardId: "dashboard-1",
  placementId: "placement-1",
  userId: "user-1",
});

// Delete a widget (will throw if still referenced in a dashboard)
await DashboardService.deleteWidget("widget-1", "proj-123");

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment