🏗️Building & Managing Charts

Build Custom Chart & View

Part of AI Analytics - This feature extends AI Analytics with custom visualization capabilities

Chart Builder enables you to create custom visualizations for your AI analytics data. Configure metrics, filters, and chart properties through a form-based interface. Charts can be saved, edited, cloned, and added to the Custom Charts Viewer dashboard.

Access: AI Analytics > Chart Builder, then click Create Chart

CREATING A CHART

Note: Charts are dynamic—options shown depend on related selections (e.g., Line Charts show Time Grain, Pie Charts require Group By). Refer to in-app tooltips (💡 icons) for the latest details on each field.

Step 1: Basic Information

Chart Name* (required, max 255 characters) - Descriptive name for your chart

Description (optional, max 1000 characters) - Additional context about what the chart shows

Chart Type* (required)

  • Line Chart - Shows trends over time

  • Bar Chart - Compares values across categories (horizontal orientation)

  • Column Chart - Compares values across categories (vertical orientation)

  • Pie Chart - Shows proportions of a whole

💡 Tooltip available via "?" HelpIcon

Step 2: Data Configuration

Chart Mode

Mode is automatically determined by your Chart Type selection:

  • Time Series - For Line Charts (displays data over time)

  • Aggregate - For Bar, Column, and Pie Charts (summarized data)

💡 Tooltip available via "?" HelpIcon

Automatic behavior:

  • Line Chart → locks to Time Series mode

  • Bar → lock to Aggregate mode

  • Column Charts → Time Series or Aggregate mode

  • Pie Chart → locks to Aggregate mode

Time Period

Date Range (required)

  • Last 7 Days

  • Last 30 Days

  • Last 90 Days

  • Last 180 Days

  • Last 365 Days

  • Custom Range (shows Start Date and End Date inputs)

Time Grain (shown only for Time Series mode - [Line+Column Charts])

Option shown varies by Date Range - Longer Rang = larger grain

  • Auto (All ranges)

  • Hour (7 days or less)

  • Daily (All ranges)

  • Week (>7 days range)

  • Month (>60 days range)

💡 Tooltip available via "?" HelpIcon

Primary Metric

Base Metric* (required)

  • Selects the fundamental data point to measure

  • Options loaded dynamically from your data

  • Examples:

    • Costs (Currency/USD) - Total AI provider costs

    • Tokens (Count) - AI tokens processed (input + output)

    • Requests (Count) - Number of AI API requests

    • Latency (Milliseconds) - AI API response time

💡 Tooltip: "The fundamental data point you want to measure and visualize in your chart"

Calculation* (required)

  • Determines how the metric is calculated

  • Options depend on selected Base Metric

  • Common options:

    • Total - Sum all values

    • Average - Mean value

    • Per-Request Average

    • Per-Token Average

    • Per-Entity Average (requires Entity Type)

💡 Tooltip available via "?" HelpIcon

Disabled until Base Metric is selected Auto-selects first available calculation when Base Metric changes

Entity Type (required only for Per-Entity Average calculation)

  • Specifies which dimension the metric measures

  • Options loaded dynamically (e.g., API Key, Model, Customer, Agent, Product, Provider, Task)

  • Cannot be the same as Group By selection

💡 Tooltip available via "?" HelpIcon

Grouping

Primary Group By (optional, except Pie Charts require it)

  • Splits data into separate series

  • Options loaded dynamically (e.g., Provider, Model, Customer, Agent, Product, Task, none)

  • Has a different effect on each chart e.g: Each group becomes a separate slice on a bar chart

💡 Tooltip available via "?" HelpIcon

Constraints:

  • Pie Charts cannot have Group By = "none"

  • Cannot be the same as Entity Type

  • Entity Type option is removed from Group By dropdown when selected

Step 3: Filters (Optional)

Apply conditions to limit data in your chart. Multiple filters use AND logic.

💡 Tooltip available via "?" HelpIcon

Each filter contains:

Field (required)

  • Selects which data field to filter

  • Options loaded dynamically from your data

Operator (required)

  • Equals / Not Equals

  • Contains / Not Contains

  • Starts With

  • In / Not In

  • Is Null / Is Not Null

  • Greater Than / Less Than

  • Between

Value (required for most operators)

  • Input type varies by operator:

    • Standard operators: single input

    • Between: two inputs (Min, Max)

    • In/Not In: multi-value or comma-separated input

    • Is Null/Is Not Null: no input shown

Actions:

  • Click Add Filter to add a new filter

  • Click trash icon to remove a filter

Step 4: Chart Focus (Optional)

Controls which data points appear in the chart.

💡 Tooltip available via "?" HelpIcon

Focus Method:

Show All Data (default)

  • Displays all available data points

Top N Items

  • Shows only the top N items by value

  • Number of Top Items field: 1-100

  • Placeholder: "e.g., 10"

  • 💡 Tooltip available via "?" HelpIcon

Value Threshold

  • Shows only items above a minimum value

  • Min Value Threshold field: numeric (step 0.01)

  • Placeholder: "e.g., 100.00"

  • 💡 Tooltip available via "?" HelpIcon

Step 5: Review & Save

  1. Review chart in the live preview panel (right side)

  2. Verify data appears as expected

  3. Click Save to store the chart definition

  4. Chart appears in Chart Builder list

  5. Add to dashboards via Custom Charts Viewer

FIELD REFERENCE

Chart Types (4 Available)

Chart Type

Mode

Best For

Notes

Line Chart

Time Series

Trends over time

Requires Time Grain selection

Bar Chart

Aggregate

Horizontal category comparison

Group By creates grouped/stacked bars

Column Chart

Aggregate

Vertical category comparison

Group By creates grouped/stacked columns

Pie Chart

Aggregate

Proportions of a whole

Requires Group By (cannot be "none")

Calculation Types

Available calculations depend on the selected Base Metric. Common types:

Total

  • Sums all values in the time period

  • Use for: Cumulative metrics (total costs, total tokens)

Average

  • Calculates mean value across time period

  • Use for: Average latency, average cost per day

Per-Request Average

  • Average value per API request

  • Use for: Cost per request, tokens per request

Per-Token Average

  • Average value per token processed

  • Use for: Cost per token calculations

Per-Entity Average

  • Average value per entity dimension

  • Requires Entity Type selection

  • Use for: Cost per customer, usage per product

Entity Types & Grouping

Entity Types and Group By options are loaded dynamically from your data.

Common Entity Types (for Per-Entity calculations):

  • API Key, Model, Customer, Agent, Product, Provider, Task

Common Group By options (split data into series):

  • Provider, Model, Customer, Agent, Product, Task, none

Important Rules:

  • Entity Type and Group By cannot be the same

  • Pie Charts require Group By (cannot be "none")

  • Selected Entity Type is removed from Group By dropdown

Filter Operators

All 12 operators with their exact UI labels:

Operator

Label

Value Input

Use Case

equals

Equals

Single

Exact match

not_equals

Not Equals

Single

Exclude exact

contains

Contains

Text

Partial match

not_contains

Not Contains

Text

Exclude partial

starts_with

Starts With

Text

Prefix match

in

In

List

Match any in list

not_in

Not In

List

Exclude all in list

is_null

Is Null

None

Field is empty

is_not_null

Is Not Null

None

Field has value

greater_than

Greater Than

Number

Numeric >

less_than

Less Than

Number

Numeric <

between

Between

Min & Max

Range (inclusive)

VALIDATION RULES

Required Fields

  • Chart name is required

  • Chart type is required

  • Date range is required

  • Base metric is required

  • Calculation type is required

Character Limits

  • Chart name: max 255 characters

  • Description: max 1000 characters

Numeric Constraints

  • Top N count: 1-100

  • Threshold value: minimum 0

Conditional Requirements

  • Entity Type required when Calculation = "Per-Entity Average"

  • Group By required (cannot be "none") for Pie Charts

  • Custom Date Range requires both start and end dates

Cross-Field Validations

  • Entity Type and Group By cannot be the same value

  • Time Grain must be supported for selected Date Range

Filter Validations

  • Filter field is required

  • Operator is required

  • Value required for most operators (except Is Null/Is Not Null)

  • "In"/"Not In" operators require list of values

  • "Between" operator requires exactly 2 values (min, max)

CHART BEHAVIOR

Auto-Selection

Chart Mode:

  • Selecting Pie → auto-sets Aggregate mode

  • Selecting Line → auto-sets Time Series mode

  • Selecting Bar/Column → auto-sets Aggregate mode

Calculation Type:

  • When Base Metric changes, auto-selects first supported calculation

Time Grain:

  • When Date Range changes, validates current grain

  • If invalid for new range, resets to "Auto"

Conditional Visibility

Time Grain field: Only shown when mode = Time Series (Line + Column Charts)

Custom Date fields: Only shown when Date Range = "Custom Range"

Entity Type field: Only shown when Calculation = "Per-Entity Average"

Focus Method inputs:

  • Top N field: shown when Focus Method = "Top N Items"

  • Threshold field: shown when Focus Method = "Value Threshold"

Filter Behavior

When Field changes:

  • Operator options update to match field's supported operators

  • Value input resets

When Operator changes:

  • Value input type changes:

    • "Between" → two inputs (Min/Max)

    • "In"/"Not In" → multi-select or comma-separated

    • "Is Null"/"Is Not Null" → no input shown

    • Others → single input

Group By Filtering

When Entity Type is selected for Per-Entity calculations:

  • That entity type is automatically removed from Group By options

  • Prevents selecting the same dimension for both fields

TIPS & BEST PRACTICES

Naming:

  • Use descriptive names that indicate what, how, and scope

  • Good: "Monthly AI Costs by Product"

  • Avoid: "Chart 1" or "Test"

Chart Selection:

  • Line Charts: trends over time

  • Bar/Column Charts: category comparisons

  • Pie Charts: proportional breakdowns (limit to 8-10 categories)

Performance:

  • Use Chart Focus (Top N or Threshold) for large datasets

  • Choose appropriate Time Grain (hourly over 90 days = many data points)

  • Apply filters to reduce data volume before visualization

Data Quality:

  • Validate data in live preview before saving

  • Use filters to exclude test or invalid data

  • Check that Group By produces manageable number of series

Last updated

Was this helpful?