Skip to main content
Using Sample Data: The examples on this page use fields from our sample dataset. Download it and create an evaluation with it to follow along with this tutorial.
Scatter Plot Widget Example

​
When to Use

Use scatter plot widgets to:
  • Explore correlations between two numerical metrics
  • Identify outliers in multi-dimensional data
  • Visualize X-Y relationships with optional bubble sizing
  • Spot clusters or patterns across evaluation items

​
Configuration

​
Required Fields

​
title
string
required
Widget display name shown on the dashboard
​
type
string
required
Must be set to “scatter”
​
query
object
required
SeriesQuery selecting at least two numeric columns

​
X-Axis Configuration (One Required)

You must provide either x_column or x_column_group, but not both:
​
config.x_column
string
Column name for the x-axis. Must be a numeric column.Example: "accuracy_score" - plots accuracy on the x-axis
​
config.x_column_group
string[]
Array of column names for multi-dimensional grouping on the x-axis.Example: ["agent_name", "accuracy_score"]

​
Query Requirements

Scatter plot widgets require a SeriesQuery with:
  • At least two numeric columns selected (one for x-axis, one for y-axis)
  • Optional GROUP BY for creating grouped scatter points
  • When grouped, aggregations determine the plotted values and dot size scales dynamically based on the count
Dot sizes are dynamically scaled based on the aggregation value, with the maximum size determined by the largest value in the dataset.

​
Creating in the UI

1

Open Widget Creator

From your dashboard, click “Add Widget” and select “Scatter Plot”
2

Enter Title

Give your chart a descriptive name (e.g., “Accuracy vs. Relevance”)
3

Configure Axes

Scatter Plot Form
  • X-Axis: Select the numeric column for the horizontal axis
  • Y-Axis: The remaining numeric columns become the y-axis values
  • Group By: Optionally group data points by a categorical dimension
  • Filter: Add conditions to narrow the data (optional)
4

Create Widget

Click “Add” to generate the scatter plot
Created Scatter Plot Widget

​
Output Format

Scatter plot widgets return row data for each point: 
{
  "type": "series",
  "data": [
    {"accuracy_score": 92, "relevance_score": 85, "count": 5},
    {"accuracy_score": 78, "relevance_score": 91, "count": 3},
    {"accuracy_score": 88, "relevance_score": 82, "count": 7}
  ]
}
Each data point represents a dot on the scatter plot. When grouped, the aggregation value determines both the position and the dot size.

​
Example Use Cases

​
Use Case 1: Accuracy vs. Relevance Scores

Explore the relationship between accuracy and relevance across evaluation items. 
widget = client.evaluation_dashboards.widgets.create(
    dashboard_id=dashboard.id,
    title="Accuracy vs. Relevance",
    type="scatter",
    query={
        "select": [
            {
                "expression": {
                    "type": "COLUMN",
                    "column": "accuracy_score",
                    "source": "data"
                }
            },
            {
                "expression": {
                    "type": "COLUMN",
                    "column": "relevance_score",
                    "source": "data"
                }
            }
        ]
    },
    config={
        "x_column": "accuracy_score"
    }
)

​
Use Case 2: Overall Score vs. Response Length

Explore whether longer responses correlate with higher or lower scores. 
widget = client.evaluation_dashboards.widgets.create(
    dashboard_id=dashboard.id,
    title="Overall Score vs. Response Length",
    type="scatter",
    query={
        "select": [
            {
                "expression": {
                    "type": "COLUMN",
                    "column": "overall_score",
                    "source": "data"
                }
            },
            {
                "expression": {
                    "type": "COLUMN",
                    "column": "response_length",
                    "source": "data"
                }
            }
        ]
    },
    config={
        "x_column": "overall_score"
    }
)