---
title: "Create Widget"
method: POST
path: "/v1/widgets"
tags: ["Widgets"]
---

# Create Widget

`POST /v1/widgets`

Create a widget with its metrics; optionally link it to a dashboard in the same call.

## Headers

- `X-API-Key` string, required

## Request body

- CreateWidgetBody — Create a widget. Non-table charts require at least one metric. filters apply to any widget type; column_visibility is stored for table + observability only.
  - `name` string, required
  - `description` string, nullable
  - `chart_type` 'line' | 'bar' | 'pie' | 'table' | 'kpi' | 'pivot_table' | 'histogram', required
  - `chart_mode` 'time_series' | 'categorical', nullable
  - `data_type` 'observability' | 'simulation'
  - `bar_mode` 'stacked' | 'side_by_side', nullable
  - `aggregation` string[]
  - `time_bucket` 'hour' | 'day' | 'week' | 'month', nullable
  - `group_by` union
    - 'agent' | 'labels' | 'tool_call' | 'age' | 'gender' | 'simulation'
    - string
  - `simulation_ids` integer[] — Required (non-empty) when group_by='simulation'
  - `show_indeterminate` boolean
  - `filters` unknown[], nullable
    - unknown
  - `column_visibility` object, nullable
  - `metrics` WidgetMetricInput[] — Metrics to plot; required unless chart_type='table'
    - `metric` string, required — Metric key, e.g. 'call_count', 'latency', 'custom_metric', 'goal', 'tool_call', 'trace_attribute'
    - `custom_metric_id` string, nullable — Required when metric='custom_metric': id from the custom metrics API
    - `goal` string, nullable — Goal text when metric='goal'
    - `tool_call_id` string, nullable — Required when metric='tool_call'
    - `metadata_path` string, nullable — Trace attribute path when metric='trace_attribute'
    - `threshold_operator` 'lt' | 'lte' | 'gt' | 'gte', nullable — With threshold_value: graph the share of conversations meeting the condition instead of the metric's own value
    - `threshold_value` number, nullable — Compared against the metric's per-conversation value; set together with threshold_operator
    - `metadata_type` string, nullable — Trace attribute value type when metric='trace_attribute'
  - `dashboard_id` string, nullable — If provided, the widget is also linked to this dashboard

## Response `200`

Successful Response

- WidgetModel
  - `id` string, required
  - `organization_id` string, nullable
  - `name` string, required
  - `description` string, nullable
  - `chart_type` string, required
  - `chart_mode` string, nullable
  - `data_type` string, required
  - `applies_to_all_agents` boolean
  - `bar_mode` string, nullable
  - `aggregation` string[], nullable
  - `time_bucket` string, nullable
  - `group_by` string, nullable
  - `simulation_ids` integer[], nullable
  - `show_indeterminate` boolean, nullable
  - `filters` unknown
  - `column_visibility` unknown
  - `created_by` string, nullable
  - `created_at` string, nullable
  - `updated_at` string, nullable
  - `widget_metrics` WidgetMetricModel[]
    - `metric` string, required — Metric key, e.g. 'call_count', 'latency', 'custom_metric', 'goal', 'tool_call', 'trace_attribute'
    - `custom_metric_id` string, nullable — Required when metric='custom_metric': id from the custom metrics API
    - `goal` string, nullable — Goal text when metric='goal'
    - `tool_call_id` string, nullable — Required when metric='tool_call'
    - `metadata_path` string, nullable — Trace attribute path when metric='trace_attribute'
    - `threshold_operator` 'lt' | 'lte' | 'gt' | 'gte', nullable — With threshold_value: graph the share of conversations meeting the condition instead of the metric's own value
    - `threshold_value` number, nullable — Compared against the metric's per-conversation value; set together with threshold_operator
    - `metadata_type` string, nullable — Trace attribute value type when metric='trace_attribute'
    - `id` string, nullable
    - `widget_id` string, nullable
  - `layout` WidgetLayoutModel — Position and size of a widget on a dashboard grid.
    - `x` integer, required — Column position, 1-based
    - `y` 1 | 2 | 3, required — Row position
    - `w` 1 | 2 | 3, required — Width in grid units
    - `h` 1 | 2 | 3, required — Height in grid units

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/getbluejay/apis/bluejay-api.md) · [All operations](https://skmtc.net/getbluejay/apis/bluejay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbluejay/bluejay-api/versions/f48cef80963f/schema)