Widgets

Widgets are the building blocks of dashboards. Each widget has a query configuration and a visualization type.

Creating a widget

POST /api/widgets
{
  "dashboardId": "uuid",
  "title": "User Registrations",
  "query": {
    "measures": ["count"],
    "groupBy": ["interactions.resourceType"],
    "filters": [
      {
        "field": "interactions.action",
        "operator": "equals",
        "value": "Register"
      }
    ],
    "timeRange": {
      "type": "relative",
      "value": "7d"
    }
  },
  "config": {
    "visualization": {
      "type": "bar",
      "options": {
        "orientation": "vertical",
        "showDataLabels": true
      }
    }
  }
}

Chart types

Bar chart

Compare values across categories. Supports vertical/horizontal orientation, stacked/grouped bars, and data labels.

Line chart

Show trends over time. Supports smooth/straight lines, area fill, and multiple series.

Pie chart

Display proportions. Supports full pie or donut style with percentage labels.

Stat

Single value display with large font, trend indicators, and comparison to previous period.

Table

Sortable columns with pagination, search, and CSV export.

Query configuration

Metrics

• count — Number of interactions
• sum — Sum of a numeric field
• avg — Average of a numeric field
• min / max — Min/max of a numeric field

Group by

• interactions.resourceType — Group by resource type
• interactions.action — Group by action
• interactions.origin — Group by origin
• Custom interaction fields

Time range

• Relative: 1h, 24h, 7d, 30d, 90d
• Absolute: { "type": "absolute", "start": "2024-01-01", "end": "2024-12-31" }

Filters

• equals, not_equals, contains, greater_than, less_than

Color customization

Map specific values to colors:

{
  "colorOverrides": [
    { "value": "Error", "color": "#ef4444" },
    { "value": "Success", "color": "#22c55e" }
  ]
}

API reference