---
title: "List Widgets"
method: GET
path: "/v1/widgets"
tags: ["Widgets"]
---

# List Widgets

`GET /v1/widgets`

List all widgets in the organization (with their metrics), newest first.

## Query parameters

- `data_type` 'observability' | 'simulation', nullable

## Headers

- `X-API-Key` string, required

## 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
  - `color_overrides` object, nullable — The colour the chart draws each series or slice in, keyed by its label lowercased. Written whole when a widget is saved, so it names every label rather than only the ones a person changed.
  - `center_label` WidgetCenterLabelModel — Pie only: what the donut hole says.
    - `slice` string, nullable — Slice whose share fills the hole. Omit for the largest slice.
    - `clamp_pct` number, nullable — Collapses the rounding edges: 1 turns 99.6% into '>99%' and 0.4% into '<1%'. An exact 0 or 100 is left alone.
    - `label` string, nullable — Caption under the percentage
  - `show_legend` boolean — Whether the chart draws its colour key
  - `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 — Where a widget sits on a dashboard and how big it is. The field names are older than the grid they describe: x is the row and y is the column, both 1-based. The dashboard is six columns wide, and height is counted in 50px steps, so h=6 is the 300px a widget used to be and the range 2..18 is 100px..900px.
    - `x` integer, required — Row, 1-based, top to bottom
    - `y` integer, required — Column within the row, 1..6
    - `w` integer, required — Width in columns, 1..6
    - `h` integer, required — Height in 50px steps, 2..18 (100px..900px)

## Other responses

- `422` — Validation Error

## Changes

> 19 revisions in range; 14 could not be searched.

- **2026-07-26** `44d183272ce1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/getbluejay/apis/bluejay-api/changes/v1/widgets/get.md)

---

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