## Create Evaluation Dashboard

**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.

### Body Parameters

- `name: string`

  Dashboard name

- `description: optional string`

  Optional description of the dashboard

- `evaluation_group_id: optional string`

  Evaluation group ID (XOR with evaluation_id)

- `evaluation_id: optional string`

  Evaluation ID (XOR with evaluation_group_id)

- `tags: optional array of string`

  The tags associated with the entity

- `template_dashboard_id: optional string`

  Optional dashboard ID to use as template. Copies widget_order from template.

- `widget_order: optional array of string`

  Ordered array of widget IDs to display on this dashboard

### Returns

- `EvaluationDashboard object { id, account_id, created_at, 13 more }`

  - `id: string`

    Unique identifier of the dashboard

  - `account_id: string`

    Account that owns this dashboard

  - `created_at: string`

    When the dashboard was created

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `name: string`

    Dashboard name

  - `tags: array of string`

    The tags associated with the entity

  - `updated_at: string`

    When the dashboard was last updated

  - `archived_at: optional string`

    When the dashboard was archived (soft-deleted)

  - `description: optional string`

    Dashboard description

  - `error_message: optional string`

    Error message if computation failed

  - `evaluation_group_id: optional string`

    Evaluation group ID

  - `evaluation_id: optional string`

    Evaluation ID

  - `object: optional "evaluation_dashboard"`

    - `"evaluation_dashboard"`

  - `widget_order: optional array of string`

    Ordered array of widget IDs

  - `widget_results: optional array of EvaluationDashboardWidgetResult`

    Widget results for this dashboard. Populated with 'widget_results' view.

    - `id: string`

      Unique identifier of the widget result

    - `account_id: string`

      Account that owns this widget result

    - `computation_status: "pending" or "completed" or "failed"`

      Status of the computation

      - `"pending"`

      - `"completed"`

      - `"failed"`

    - `created_at: string`

      When the widget result was created

    - `widget_id: string`

      Unique identifier of the widget

    - `computation_job_id: optional string`

      Temporal workflow ID or job ID for async computation tracking

    - `computed_at: optional string`

      Timestamp when computation completed successfully

    - `computed_result: optional map[unknown]`

      Cached computation results

    - `error_message: optional string`

      Error message if computation failed

    - `evaluation_group_id: optional string`

      FK to evaluation_groups. Null if result is for a single evaluation.

    - `evaluation_id: optional string`

      FK to evaluations. Null if result is for an evaluation group.

    - `object: optional "evaluation_dashboard_widget_result"`

      - `"evaluation_dashboard_widget_result"`

    - `widget: optional EvaluationDashboardWidget`

      Widget that this result is for

      - `id: string`

        Unique identifier of the widget

      - `account_id: string`

        Account that owns this widget

      - `created_at: string`

        When the widget was created

      - `title: string`

        Widget title

      - `type: EvaluationWidgetTypeEnum`

        Widget type

        - `"bar"`

        - `"histogram"`

        - `"donut"`

        - `"scatter"`

        - `"metric"`

        - `"table"`

        - `"markdown"`

        - `"heading"`

        - `"timeseries"`

      - `archived_at: optional string`

        When the widget was archived (soft-deleted)

      - `config: optional map[unknown]`

        Chart-specific display configuration

      - `object: optional "evaluation_dashboard_widget"`

        - `"evaluation_dashboard_widget"`

      - `query: optional SeriesQuery or MetricQuery`

        Structured query AST for metric computation (SeriesQuery or MetricQuery)

        - `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: 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"}

              - `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"`

                  - `"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

                  - `"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"`

                  - `"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`

            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

                - `"="`

                - `"!="`

                - `">"`

                - `"<"`

                - `">="`

                - `"<="`

                - `"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.

                - `string`

                - `number`

                - `boolean`

                - `array of unknown`

            - `logicalOperators: optional array of "AND" or "OR"`

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

              - `"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

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

            Sort order

            - `column: string`

              Column name to sort by

            - `direction: optional "ASC" or "DESC"`

              Sort direction

              - `"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: 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"}

            - `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`

            Filter conditions (WHERE clause)

          - `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.

  - `widgets: optional array of EvaluationDashboardWidget`

    Widgets associated with this dashboard. Populated with 'widgets' view.

    - `id: string`

      Unique identifier of the widget

    - `account_id: string`

      Account that owns this widget

    - `created_at: string`

      When the widget was created

    - `title: string`

      Widget title

    - `type: EvaluationWidgetTypeEnum`

      Widget type

    - `archived_at: optional string`

      When the widget was archived (soft-deleted)

    - `config: optional map[unknown]`

      Chart-specific display configuration

    - `object: optional "evaluation_dashboard_widget"`

    - `query: optional SeriesQuery or MetricQuery`

      Structured query AST for metric computation (SeriesQuery or MetricQuery)

### Example

```http
curl https://api.egp.scale.com/v5/evaluation-dashboards \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "name": "x"
        }'
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "name": "name",
  "tags": [
    "string"
  ],
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "description": "description",
  "error_message": "error_message",
  "evaluation_group_id": "evaluation_group_id",
  "evaluation_id": "evaluation_id",
  "object": "evaluation_dashboard",
  "widget_order": [
    "string"
  ],
  "widget_results": [
    {
      "id": "id",
      "account_id": "account_id",
      "computation_status": "pending",
      "created_at": "2019-12-27T18:11:19.117Z",
      "widget_id": "widget_id",
      "computation_job_id": "computation_job_id",
      "computed_at": "2019-12-27T18:11:19.117Z",
      "computed_result": {
        "foo": "bar"
      },
      "error_message": "error_message",
      "evaluation_group_id": "evaluation_group_id",
      "evaluation_id": "evaluation_id",
      "object": "evaluation_dashboard_widget_result",
      "widget": {
        "id": "id",
        "account_id": "account_id",
        "created_at": "2019-12-27T18:11:19.117Z",
        "title": "title",
        "type": "bar",
        "archived_at": "2019-12-27T18:11:19.117Z",
        "config": {
          "foo": "bar"
        },
        "object": "evaluation_dashboard_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"
            }
          ]
        }
      }
    }
  ],
  "widgets": [
    {
      "id": "id",
      "account_id": "account_id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "title": "title",
      "type": "bar",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "config": {
        "foo": "bar"
      },
      "object": "evaluation_dashboard_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"
          }
        ]
      }
    }
  ]
}
```