Skip to content
sgp
API Reference
Evaluation Dashboards
Widgets

Update Dashboard Widget

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.

Path ParametersExpand Collapse
dashboard_id: string
widget_id: string
Body ParametersJSONExpand Collapse
config: optional map[unknown]

Chart-specific display configuration

query: optional SeriesQuery { select, evaluation_ids, filter, 4 more } or MetricQuery { select, evaluation_ids, filter, latest_only }

Structured query AST for metric computation (SeriesQuery or MetricQuery)

One of the following:
SeriesQuery object { 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

select: array of SelectItem { expression, alias }
expression: object { column, source, type } or object { column, function, evaluation_ids, 3 more }

Reference to a column from evaluation_items.data

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

One of the following:
Column object { column, source, type }

Reference to a column from evaluation_items.data

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

column: string

Column name from evaluation_items.data

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "COLUMN"
Aggregation object { column, function, evaluation_ids, 3 more }

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: string

Column to aggregate, or '' for COUNT()

function: "COUNT" or "SUM" or "AVG" or 7 more

Supported aggregation functions

One of the following:
"COUNT"
"SUM"
"AVG"
"MIN"
"MAX"
"STDDEV"
"VARIANCE"
"PERCENTILE"
"COUNT_DISTINCT"
"PERCENTAGE"
evaluation_ids: optional array of string

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

params: optional map[unknown]

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

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "AGGREGATION"
alias: optional string

Optional alias for the selected item

evaluation_ids: optional array of string

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 { conditions, logicalOperators }

Filter conditions (WHERE clause)

conditions: array of object { column, operator, source, value }
column: string

Column name to filter on

operator: "=" or "!=" or ">" or 9 more

Comparison operator

One of the following:
"="
"!="
">"
"<"
">="
"<="
"IN"
"NOT IN"
"LIKE"
"NOT LIKE"
"IS NULL"
"IS NOT NULL"
source: optional string

Column source: ‘data’ or ‘task_result_cache’

value: optional string or number or boolean or array of unknown

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

One of the following:
string
number
boolean
array of unknown
logicalOperators: optional array of "AND" or "OR"

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

One of the following:
"AND"
"OR"
groupBy: optional array of string

Columns to group by

latest_only: optional boolean

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 number

Max rows to return

minimum1
orderBy: optional array of object { column, direction, source }

Sort order

column: string

Column name to sort by

direction: optional "ASC" or "DESC"

Sort direction

One of the following:
"ASC"
"DESC"
source: optional string

Column source: ‘data’ or ‘task_result_cache’

MetricQuery object { select, evaluation_ids, filter, latest_only }

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: array of SelectItem { expression, alias }
expression: object { column, source, type } or object { column, function, evaluation_ids, 3 more }

Reference to a column from evaluation_items.data

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

One of the following:
Column object { column, source, type }

Reference to a column from evaluation_items.data

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

column: string

Column name from evaluation_items.data

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "COLUMN"
Aggregation object { column, function, evaluation_ids, 3 more }

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: string

Column to aggregate, or '' for COUNT()

function: "COUNT" or "SUM" or "AVG" or 7 more

Supported aggregation functions

One of the following:
"COUNT"
"SUM"
"AVG"
"MIN"
"MAX"
"STDDEV"
"VARIANCE"
"PERCENTILE"
"COUNT_DISTINCT"
"PERCENTAGE"
evaluation_ids: optional array of string

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

params: optional map[unknown]

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

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "AGGREGATION"
alias: optional string

Optional alias for the selected item

evaluation_ids: optional array of string

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 { conditions, logicalOperators }

Filter conditions (WHERE clause)

conditions: array of object { column, operator, source, value }
column: string

Column name to filter on

operator: "=" or "!=" or ">" or 9 more

Comparison operator

One of the following:
"="
"!="
">"
"<"
">="
"<="
"IN"
"NOT IN"
"LIKE"
"NOT LIKE"
"IS NULL"
"IS NOT NULL"
source: optional string

Column source: ‘data’ or ‘task_result_cache’

value: optional string or number or boolean or array of unknown

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

One of the following:
string
number
boolean
array of unknown
logicalOperators: optional array of "AND" or "OR"

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

One of the following:
"AND"
"OR"
latest_only: optional boolean

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.

title: optional string

Widget title

maxLength256
minLength1
ReturnsExpand Collapse
EvaluationDashboardWidgetWithResult object { id, account_id, created_at, 6 more }

Response model for widget creation - includes widget and computed result

id: string

Unique identifier of the widget

account_id: string

Account that owns this widget

created_at: string

When the widget was created

formatdate-time
title: string

Widget title

type: EvaluationWidgetTypeEnum

Widget type

One of the following:
"bar"
"histogram"
"donut"
"scatter"
"metric"
"table"
"markdown"
"heading"
"timeseries"
config: optional map[unknown]

Display configuration

object: optional "evaluation_widget"
query: optional SeriesQuery { select, evaluation_ids, filter, 4 more } or MetricQuery { select, evaluation_ids, filter, latest_only }

Structured query AST for computation (SeriesQuery or MetricQuery)

One of the following:
SeriesQuery object { 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

select: array of SelectItem { expression, alias }
expression: object { column, source, type } or object { column, function, evaluation_ids, 3 more }

Reference to a column from evaluation_items.data

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

One of the following:
Column object { column, source, type }

Reference to a column from evaluation_items.data

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

column: string

Column name from evaluation_items.data

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "COLUMN"
Aggregation object { column, function, evaluation_ids, 3 more }

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: string

Column to aggregate, or '' for COUNT()

function: "COUNT" or "SUM" or "AVG" or 7 more

Supported aggregation functions

One of the following:
"COUNT"
"SUM"
"AVG"
"MIN"
"MAX"
"STDDEV"
"VARIANCE"
"PERCENTILE"
"COUNT_DISTINCT"
"PERCENTAGE"
evaluation_ids: optional array of string

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

params: optional map[unknown]

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

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "AGGREGATION"
alias: optional string

Optional alias for the selected item

evaluation_ids: optional array of string

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 { conditions, logicalOperators }

Filter conditions (WHERE clause)

conditions: array of object { column, operator, source, value }
column: string

Column name to filter on

operator: "=" or "!=" or ">" or 9 more

Comparison operator

One of the following:
"="
"!="
">"
"<"
">="
"<="
"IN"
"NOT IN"
"LIKE"
"NOT LIKE"
"IS NULL"
"IS NOT NULL"
source: optional string

Column source: ‘data’ or ‘task_result_cache’

value: optional string or number or boolean or array of unknown

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

One of the following:
string
number
boolean
array of unknown
logicalOperators: optional array of "AND" or "OR"

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

One of the following:
"AND"
"OR"
groupBy: optional array of string

Columns to group by

latest_only: optional boolean

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 number

Max rows to return

minimum1
orderBy: optional array of object { column, direction, source }

Sort order

column: string

Column name to sort by

direction: optional "ASC" or "DESC"

Sort direction

One of the following:
"ASC"
"DESC"
source: optional string

Column source: ‘data’ or ‘task_result_cache’

MetricQuery object { select, evaluation_ids, filter, latest_only }

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: array of SelectItem { expression, alias }
expression: object { column, source, type } or object { column, function, evaluation_ids, 3 more }

Reference to a column from evaluation_items.data

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

One of the following:
Column object { column, source, type }

Reference to a column from evaluation_items.data

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

column: string

Column name from evaluation_items.data

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "COLUMN"
Aggregation object { column, function, evaluation_ids, 3 more }

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: string

Column to aggregate, or '' for COUNT()

function: "COUNT" or "SUM" or "AVG" or 7 more

Supported aggregation functions

One of the following:
"COUNT"
"SUM"
"AVG"
"MIN"
"MAX"
"STDDEV"
"VARIANCE"
"PERCENTILE"
"COUNT_DISTINCT"
"PERCENTAGE"
evaluation_ids: optional array of string

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

params: optional map[unknown]

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

source: optional string

Column source: ‘data’ or ‘task_result_cache’

type: optional "AGGREGATION"
alias: optional string

Optional alias for the selected item

evaluation_ids: optional array of string

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 { conditions, logicalOperators }

Filter conditions (WHERE clause)

conditions: array of object { column, operator, source, value }
column: string

Column name to filter on

operator: "=" or "!=" or ">" or 9 more

Comparison operator

One of the following:
"="
"!="
">"
"<"
">="
"<="
"IN"
"NOT IN"
"LIKE"
"NOT LIKE"
"IS NULL"
"IS NOT NULL"
source: optional string

Column source: ‘data’ or ‘task_result_cache’

value: optional string or number or boolean or array of unknown

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

One of the following:
string
number
boolean
array of unknown
logicalOperators: optional array of "AND" or "OR"

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

One of the following:
"AND"
"OR"
latest_only: optional boolean

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 { id, computation_status, widget_id, 3 more }

Computed result for this widget

id: string

Unique identifier of the widget result

computation_status: string

Status: pending, completed, or failed

widget_id: string

Widget ID this result belongs to

computed_at: optional string

When computation completed

formatdate-time
computed_result: optional map[unknown]

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

error_message: optional string

Error message if computation failed

Update Dashboard Widget

curl https://api.egp.scale.com/v5/evaluation-dashboards/$DASHBOARD_ID/widgets/$WIDGET_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{}'
{
  "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
{
  "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"
  }
}