Documentation

Evaluation Dashboards

evaluation_dashboards

Methods

Create Evaluation Dashboard ->
EvaluationDashboard
post/v5/evaluation-dashboards

Create a dashboard bound to exactly one evaluation or evaluation group.

The request must set exactly one of evaluation_id or evaluation_group_id (enforced as XOR) — supplying both or neither is rejected, and the referenced evaluation or group must already exist in the caller's account or the call fails with a not-found error. If template_dashboard_id is provided, the new dashboard copies that template's widget_order and synchronously computes a result for each of those widgets against the new dashboard's evaluation data before returning. Any widget_order supplied is validated to contain only existing, non-duplicate widget IDs. The dashboard is created and returned immediately; individual widgets are added afterward through the widget sub-endpoints.

List Evaluation Dashboards -> CursorPage<
EvaluationDashboard
>
get/v5/evaluation-dashboards

List dashboards in the caller's account, paginated, with optional filters.

Filter to a single evaluation with evaluation_id or to a group with evaluation_group_id; passing both is rejected, since a dashboard is bound to one or the other. tags matches case-insensitively (values are lowercased before lookup), created_by_ids filters by creator identity, and search matches the dashboard name and tags. Archived dashboards are excluded unless include_archived is true. The returned items carry only the dashboards' own fields — widgets and widget results are never embedded here; use the get-by-id endpoint with the widgets/widget_results views to load those.

Get Evaluation Dashboard ->
EvaluationDashboard
get/v5/evaluation-dashboards/{dashboard_id}

Fetch a single dashboard by ID within the caller's account.

By default only the dashboard's own fields are returned. Pass views=widgets and/or views=widget_results to eagerly load the dashboard's widgets and their last-computed results as nested relationships; without those views the widgets and widget_results fields are omitted from the response entirely. Set include_archived=true to retrieve a soft-deleted dashboard. Returns a not-found error if no matching dashboard exists in the account.

Patch Evaluation Dashboard ->
EvaluationDashboard
patch/v5/evaluation-dashboards/{dashboard_id}

Partially update a dashboard's name, description, tags, or widget_order.

Only these mutable fields can change — the dashboard's bound evaluation or group is fixed at creation and cannot be reassigned here, and unset fields are left untouched (partial-update semantics). Reorder existing widgets by sending a new widget_order, whose entries are validated to be existing, non-duplicate widget IDs before the update is applied; creating and attaching new widgets is done through the widget sub-endpoints, not by editing widget_order. Archived dashboards cannot be updated and return a not-found error.

Delete Evaluation Dashboard ->
EvaluationDashboard
delete/v5/evaluation-dashboards/{dashboard_id}

Soft-delete a dashboard by setting its archived timestamp.

The dashboard row is retained and marked archived rather than physically removed, so it stops appearing in default listings but can still be fetched with include_archived=true; the archived dashboard is returned by this call. Associated widgets and widget results are not deleted or detached. Returns a not-found error if the dashboard does not exist in the caller's account.

Domain types

EvaluationDashboard = { id, account_id, created_at, 13 more... }
Evaluation Dashboards

Widgets

evaluation_dashboards.widgets

Methods

Add Widget To Dashboard ->
EvaluationDashboardWidgetWithResult
post/v5/evaluation-dashboards/{dashboard_id}/widgets

Create a new widget, append it to the dashboard, and compute its result in one call.

The widget is persisted as its own entity, its ID is appended to the dashboard's widget_order, and — unless it is a markdown or heading widget — its result is computed synchronously against the dashboard's evaluation (or evaluation-group) data before the response returns. Validation is type-specific: markdown requires config.content, bar/histogram/donut/scatter require exactly one of config.x_column or config.x_column_group, table configs with conditional formatting are schema-validated, and all other chart types require a query. The dashboard must exist and not be archived. A computation failure does not fail the request: the widget is still created and returned with a result whose computation_status is failed and an error_message set, while markdown and heading widgets return a null result.

Update Dashboard Widget ->
EvaluationDashboardWidgetWithResult
patch/v5/evaluation-dashboards/{dashboard_id}/widgets/{widget_id}

Update a widget's fields within this dashboard, using copy-on-write for shared widgets.

If the widget belongs only to this dashboard it is updated in place; if it is referenced by more than one dashboard, a new widget is created with the updates applied and swapped into this dashboard's widget_order, leaving the other dashboards' copy untouched. The widget must already be in this dashboard's widget_order, otherwise the call is rejected. The result is recomputed synchronously when the query changes or when the widget was cloned; otherwise the existing cached result is returned. For table widgets, conditional-formatting column references are re-resolved against the (possibly updated) query on each save. The dashboard must exist and not be archived.

Remove Widget From Dashboard ->
delete/v5/evaluation-dashboards/{dashboard_id}/widgets/{widget_id}

Detach a widget from this dashboard without deleting the widget itself.

This removes the widget's ID from the dashboard's widget_order only; the underlying widget entity and any computed widget results are left intact, so a widget shared with other dashboards continues to work there. The widget must currently be in this dashboard's widget_order, otherwise a not-found error is returned. Responds with 204 No Content on success.

path Parameters
dashboard_id: string
widget_id: string
Request example

Domain types

EvaluationDashboardWidget = { id, account_id, created_at, 6 more... }
EvaluationDashboardWidgetResult = { id, account_id, computation_status, 10 more... }
EvaluationDashboardWidgetResultResponse = { id, computation_status, widget_id, 3 more... }

Computed result for a widget - used in widget creation response

EvaluationDashboardWidgetWithResult = { id, account_id, created_at, 6 more... }

Response model for widget creation - includes widget and computed result

EvaluationWidgetTypeEnum = "bar" | "histogram" | "donut" | 6 more...

Widget types for dashboard visualizations

Filter = { conditions, logicalOperators }

Filter clause with conditions connected by logical operators.

Conditions are evaluated left-to-right without precedence (no nesting/parentheses). Example: condition1 AND condition2 OR condition3 evaluates as ((condition1 AND condition2) OR condition3)

Example: { "conditions": [ {"column": "score", "operator": ">", "value": 0.5}, {"column": "category", "operator": "=", "value": "test"} ], "logicalOperators": ["AND"] }

MetricQuery = { select, evaluation_ids, filter, 1 more... }

Query that returns a single metric value (used for metric widgets).

Used for widget type: metric. Enforces exactly 1 aggregation in select. Returns: {"type": "metric", "data": ...}

Example SQL equivalent: SELECT AVG(score) as average_score FROM evaluation_items

SelectItem = { expression, alias }

Column in SELECT clause

SeriesQuery = { select, evaluation_ids, filter, 4 more... }

Query that returns a series of records (used for table/bar/histogram/donut/scatter widgets).

Used for widget types: table, bar, histogram, donut, scatter. Returns: {"type": "series", "data": [...]}

Example SQL equivalent: SELECT category, AVG(score) as avg_score, COUNT(*) as count FROM evaluation_items WHERE score > 0.5 AND category = 'test' GROUP BY category ORDER BY avg_score DESC LIMIT 100