API Reference

Evaluation Dashboards

Widgets

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Add Widget to Dashboard

evaluation_dashboards.widgets.create(strdashboard_id, WidgetCreateParams**kwargs) -> 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.

ParametersExpand Collapse

dashboard_id: str

title: str

Widget title

maxLength256

minLength1

type: EvaluationWidgetTypeEnum

Widget type

One of the following:

"bar"

"histogram"

"donut"

"scatter"

"metric"

"table"

"markdown"

"heading"

"timeseries"

config: Optional[Dict[str, object]]

Chart-specific display configuration

query: Optional[Query]

Structured query AST for metric computation (SeriesQuery or MetricQuery)

One of the following:

class SeriesQuery: …

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

select: List[SelectItem]

expression: Expression

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

One of the following:

class ExpressionColumn: …

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

column: str

Column name from evaluation_items.data

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["COLUMN"]]

class ExpressionAggregation: …

Aggregation function to apply

Examples: {“type”: “AGGREGATION”, “function”: “AVG”, “column”: “score”} {“type”: “AGGREGATION”, “function”: “COUNT”, “column”: ”*”} {“type”: “AGGREGATION”, “function”: “PERCENTILE”, “column”: “score”, “params”: {“percentile”: 95}}

column: str

Column to aggregate, or '' for COUNT()

function: Literal["COUNT", "SUM", "AVG", 7 more]

Supported aggregation functions

One of the following:

"COUNT"

"SUM"

"AVG"

"MIN"

"MAX"

"STDDEV"

"VARIANCE"

"PERCENTILE"

"COUNT_DISTINCT"

"PERCENTAGE"

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs for per-aggregation filtering in evaluation group dashboards.

params: Optional[Dict[str, object]]

Function parameters (e.g., {‘percentile’: 95} for PERCENTILE, {‘percentage_filters’: Filter} for PERCENTAGE)

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["AGGREGATION"]]

alias: Optional[str]

Optional alias for the selected item

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs to compute on. Only applicable for evaluation group dashboards. If omitted, computes on all evaluations in the group.

filter: Optional[Filter]

Filter conditions (WHERE clause)

conditions: List[Condition]

column: str

Column name to filter on

operator: Literal["=", "!=", ">", 9 more]

Comparison operator

One of the following:

"="

"!="

">"

"<"

">="

"<="

"IN"

"NOT IN"

"LIKE"

"NOT LIKE"

"IS NULL"

"IS NOT NULL"

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

value: Optional[Union[str, float, bool, 2 more]]

Value to compare against. Not required for IS NULL / IS NOT NULL operators.

One of the following:

str

float

bool

List[object]

logical_operators: Optional[List[Literal["AND", "OR"]]]

Logical operators connecting conditions. Length must be len(conditions) - 1

One of the following:

"AND"

"OR"

group_by: Optional[List[str]]

Columns to group by

latest_only: Optional[bool]

When True, the widget computes against rows from only the most recent active evaluation in the group (by EvaluationORM.created_at). Only applicable for evaluation group dashboards. Composes with evaluation_ids (latest within the subset). Cannot be combined with per-aggregation evaluation_ids; the use case enforces these rules.

limit: Optional[int]

Max rows to return

minimum1

order_by: Optional[List[OrderBy]]

Sort order

column: str

Column name to sort by

direction: Optional[Literal["ASC", "DESC"]]

Sort direction

One of the following:

"ASC"

"DESC"

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

class MetricQuery: …

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

select: List[SelectItem]

expression: Expression

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

One of the following:

class ExpressionColumn: …

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

column: str

Column name from evaluation_items.data

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["COLUMN"]]

class ExpressionAggregation: …

Aggregation function to apply

Examples: {“type”: “AGGREGATION”, “function”: “AVG”, “column”: “score”} {“type”: “AGGREGATION”, “function”: “COUNT”, “column”: ”*”} {“type”: “AGGREGATION”, “function”: “PERCENTILE”, “column”: “score”, “params”: {“percentile”: 95}}

column: str

Column to aggregate, or '' for COUNT()

function: Literal["COUNT", "SUM", "AVG", 7 more]

Supported aggregation functions

One of the following:

"COUNT"

"SUM"

"AVG"

"MIN"

"MAX"

"STDDEV"

"VARIANCE"

"PERCENTILE"

"COUNT_DISTINCT"

"PERCENTAGE"

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs for per-aggregation filtering in evaluation group dashboards.

params: Optional[Dict[str, object]]

Function parameters (e.g., {‘percentile’: 95} for PERCENTILE, {‘percentage_filters’: Filter} for PERCENTAGE)

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["AGGREGATION"]]

alias: Optional[str]

Optional alias for the selected item

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs to compute on. Only applicable for evaluation group dashboards. If omitted, computes on all evaluations in the group.

filter: Optional[Filter]

Filter conditions (WHERE clause)

conditions: List[Condition]

column: str

Column name to filter on

operator: Literal["=", "!=", ">", 9 more]

Comparison operator

One of the following:

"="

"!="

">"

"<"

">="

"<="

"IN"

"NOT IN"

"LIKE"

"NOT LIKE"

"IS NULL"

"IS NOT NULL"

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

value: Optional[Union[str, float, bool, 2 more]]

Value to compare against. Not required for IS NULL / IS NOT NULL operators.

One of the following:

str

float

bool

List[object]

logical_operators: Optional[List[Literal["AND", "OR"]]]

Logical operators connecting conditions. Length must be len(conditions) - 1

One of the following:

"AND"

"OR"

latest_only: Optional[bool]

When True, the widget computes against rows from only the most recent active evaluation in the group (by EvaluationORM.created_at). Only applicable for evaluation group dashboards. Composes with evaluation_ids (latest within the subset). Cannot be combined with per-aggregation evaluation_ids; the use case enforces these rules.

ReturnsExpand Collapse

class EvaluationDashboardWidgetWithResult: …

Response model for widget creation - includes widget and computed result

id: str

Unique identifier of the widget

account_id: str

Account that owns this widget

created_at: datetime

When the widget was created

formatdate-time

title: str

Widget title

type: EvaluationWidgetTypeEnum

Widget type

One of the following:

"bar"

"histogram"

"donut"

"scatter"

"metric"

"table"

"markdown"

"heading"

"timeseries"

config: Optional[Dict[str, object]]

Display configuration

object: Optional[Literal["evaluation_widget"]]

query: Optional[Query]

Structured query AST for computation (SeriesQuery or MetricQuery)

One of the following:

class SeriesQuery: …

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

select: List[SelectItem]

expression: Expression

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

One of the following:

class ExpressionColumn: …

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

column: str

Column name from evaluation_items.data

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["COLUMN"]]

class ExpressionAggregation: …

Aggregation function to apply

Examples: {“type”: “AGGREGATION”, “function”: “AVG”, “column”: “score”} {“type”: “AGGREGATION”, “function”: “COUNT”, “column”: ”*”} {“type”: “AGGREGATION”, “function”: “PERCENTILE”, “column”: “score”, “params”: {“percentile”: 95}}

column: str

Column to aggregate, or '' for COUNT()

function: Literal["COUNT", "SUM", "AVG", 7 more]

Supported aggregation functions

One of the following:

"COUNT"

"SUM"

"AVG"

"MIN"

"MAX"

"STDDEV"

"VARIANCE"

"PERCENTILE"

"COUNT_DISTINCT"

"PERCENTAGE"

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs for per-aggregation filtering in evaluation group dashboards.

params: Optional[Dict[str, object]]

Function parameters (e.g., {‘percentile’: 95} for PERCENTILE, {‘percentage_filters’: Filter} for PERCENTAGE)

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["AGGREGATION"]]

alias: Optional[str]

Optional alias for the selected item

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs to compute on. Only applicable for evaluation group dashboards. If omitted, computes on all evaluations in the group.

filter: Optional[Filter]

Filter conditions (WHERE clause)

conditions: List[Condition]

column: str

Column name to filter on

operator: Literal["=", "!=", ">", 9 more]

Comparison operator

One of the following:

"="

"!="

">"

"<"

">="

"<="

"IN"

"NOT IN"

"LIKE"

"NOT LIKE"

"IS NULL"

"IS NOT NULL"

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

value: Optional[Union[str, float, bool, 2 more]]

Value to compare against. Not required for IS NULL / IS NOT NULL operators.

One of the following:

str

float

bool

List[object]

logical_operators: Optional[List[Literal["AND", "OR"]]]

Logical operators connecting conditions. Length must be len(conditions) - 1

One of the following:

"AND"

"OR"

group_by: Optional[List[str]]

Columns to group by

latest_only: Optional[bool]

When True, the widget computes against rows from only the most recent active evaluation in the group (by EvaluationORM.created_at). Only applicable for evaluation group dashboards. Composes with evaluation_ids (latest within the subset). Cannot be combined with per-aggregation evaluation_ids; the use case enforces these rules.

limit: Optional[int]

Max rows to return

minimum1

order_by: Optional[List[OrderBy]]

Sort order

column: str

Column name to sort by

direction: Optional[Literal["ASC", "DESC"]]

Sort direction

One of the following:

"ASC"

"DESC"

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

class MetricQuery: …

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

select: List[SelectItem]

expression: Expression

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

One of the following:

class ExpressionColumn: …

Reference to a column from evaluation_items.data

Example: {“type”: “COLUMN”, “column”: “category”}

column: str

Column name from evaluation_items.data

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["COLUMN"]]

class ExpressionAggregation: …

Aggregation function to apply

Examples: {“type”: “AGGREGATION”, “function”: “AVG”, “column”: “score”} {“type”: “AGGREGATION”, “function”: “COUNT”, “column”: ”*”} {“type”: “AGGREGATION”, “function”: “PERCENTILE”, “column”: “score”, “params”: {“percentile”: 95}}

column: str

Column to aggregate, or '' for COUNT()

function: Literal["COUNT", "SUM", "AVG", 7 more]

Supported aggregation functions

One of the following:

"COUNT"

"SUM"

"AVG"

"MIN"

"MAX"

"STDDEV"

"VARIANCE"

"PERCENTILE"

"COUNT_DISTINCT"

"PERCENTAGE"

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs for per-aggregation filtering in evaluation group dashboards.

params: Optional[Dict[str, object]]

Function parameters (e.g., {‘percentile’: 95} for PERCENTILE, {‘percentage_filters’: Filter} for PERCENTAGE)

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

type: Optional[Literal["AGGREGATION"]]

alias: Optional[str]

Optional alias for the selected item

evaluation_ids: Optional[List[str]]

Optional subset of evaluation IDs to compute on. Only applicable for evaluation group dashboards. If omitted, computes on all evaluations in the group.

filter: Optional[Filter]

Filter conditions (WHERE clause)

conditions: List[Condition]

column: str

Column name to filter on

operator: Literal["=", "!=", ">", 9 more]

Comparison operator

One of the following:

"="

"!="

">"

"<"

">="

"<="

"IN"

"NOT IN"

"LIKE"

"NOT LIKE"

"IS NULL"

"IS NOT NULL"

source: Optional[str]

Column source: ‘data’ or ‘task_result_cache’

value: Optional[Union[str, float, bool, 2 more]]

Value to compare against. Not required for IS NULL / IS NOT NULL operators.

One of the following:

str

float

bool

List[object]

logical_operators: Optional[List[Literal["AND", "OR"]]]

Logical operators connecting conditions. Length must be len(conditions) - 1

One of the following:

"AND"

"OR"

latest_only: Optional[bool]

When True, the widget computes against rows from only the most recent active evaluation in the group (by EvaluationORM.created_at). Only applicable for evaluation group dashboards. Composes with evaluation_ids (latest within the subset). Cannot be combined with per-aggregation evaluation_ids; the use case enforces these rules.

result: Optional[EvaluationDashboardWidgetResultResponse]

Computed result for this widget

id: str

Unique identifier of the widget result

computation_status: str

Status: pending, completed, or failed

widget_id: str

Widget ID this result belongs to

computed_at: Optional[datetime]

When computation completed

formatdate-time

computed_result: Optional[Dict[str, object]]

Computed result data. Metric: {type: ‘metric’, data: 42}, Series: {type: ‘series’, data: [{x: ‘A’, y: 10}, …]}

error_message: Optional[str]

Error message if computation failed

Add Widget to Dashboard

Python

HTTP

TypeScript

Python

Go

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
evaluation_dashboard_widget_with_result = client.evaluation_dashboards.widgets.create(
    dashboard_id="dashboard_id",
    title="x",
    type="bar",
)
print(evaluation_dashboard_widget_with_result.id)

200 example

{
  "id": "id",
  "account_id": "account_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "title": "title",
  "type": "bar",
  "config": {
    "foo": "bar"
  },
  "object": "evaluation_widget",
  "query": {
    "select": [
      {
        "expression": {
          "column": "column",
          "source": "source",
          "type": "COLUMN"
        },
        "alias": "alias"
      }
    ],
    "evaluation_ids": [
      "string"
    ],
    "filter": {
      "conditions": [
        {
          "column": "column",
          "operator": "=",
          "source": "source",
          "value": "string"
        }
      ],
      "logicalOperators": [
        "AND"
      ]
    },
    "groupBy": [
      "string"
    ],
    "latest_only": true,
    "limit": 1,
    "orderBy": [
      {
        "column": "column",
        "direction": "ASC",
        "source": "source"
      }
    ]
  },
  "result": {
    "id": "id",
    "computation_status": "computation_status",
    "widget_id": "widget_id",
    "computed_at": "2019-12-27T18:11:19.117Z",
    "computed_result": {
      "foo": "bar"
    },
    "error_message": "error_message"
  }
}

Returns Examples

200 example

{
  "id": "id",
  "account_id": "account_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "title": "title",
  "type": "bar",
  "config": {
    "foo": "bar"
  },
  "object": "evaluation_widget",
  "query": {
    "select": [
      {
        "expression": {
          "column": "column",
          "source": "source",
          "type": "COLUMN"
        },
        "alias": "alias"
      }
    ],
    "evaluation_ids": [
      "string"
    ],
    "filter": {
      "conditions": [
        {
          "column": "column",
          "operator": "=",
          "source": "source",
          "value": "string"
        }
      ],
      "logicalOperators": [
        "AND"
      ]
    },
    "groupBy": [
      "string"
    ],
    "latest_only": true,
    "limit": 1,
    "orderBy": [
      {
        "column": "column",
        "direction": "ASC",
        "source": "source"
      }
    ]
  },
  "result": {
    "id": "id",
    "computation_status": "computation_status",
    "widget_id": "widget_id",
    "computed_at": "2019-12-27T18:11:19.117Z",
    "computed_result": {
      "foo": "bar"
    },
    "error_message": "error_message"
  }
}