System tools for Optimizely Analytics

19 min

System tools are built-in features that help Optimizely Opal take action. Each tool performs a specific task, such as creating a campaign, uploading files, or generating images. Think of tools like attachments on a Swiss Army knife. Each one has a distinct purpose that helps you get work done.

Optimizely AnalyticsOptimizely Analytics provides system tools to help you with Analytics-related tasks, in addition to the system tools already available in Opal.

Note

Ask Opal what tools it has at any time. For example, enter "Please list the tools you have with a brief description of what they do and the parameters" into Opal Chat.

Click a tool's name to expand it and learn when to use it, its required and optional parameters, and example prompts for calling the tool. If you do not provide a required parameter, Opal prompts you for it.

Dashboard management tools

Data retrieval and app configuration tools

Data ingestion tools

Exploration creation tools

When to use

Analyze a previously saved exploration to surface insights from its data.

Re-run a saved exploration with a different time range or time granularity.

Apply ad-hoc filters or sampling overrides to a saved exploration without modifying it permanently.

Analyze an exploration in the context of a dashboard, automatically applying the dashboard's always-on filters.

Parameters

explore_id – The unique identifier of a saved exploration (format: <number>_<uuid>). Must be obtained from the id field in the oa_find_explores tool response. Do not pass dashboard IDs, experiment IDs, or draft explore IDs here.

(Optional) appid – The ID of your Optimizely Analytics application for context. Opal uses the appid from your system context if available, or explicitly asks you for this value. You can often find it in the URL of your Optimizely Analytics project (signified by ?app=).

(Optional) time_range – Overrides the time range for analyzing the exploration. The agent should intelligently include this parameter when the user specifies a different time period than the exploration's default. For example, show me that exploration for the last month or re-run for January 2024 to January 2025. The object must have either a last field for relative ranges or both start and end fields for absolute ranges: For relative ranges (for example, last 30 days or past week): { "last": { "value": 30, "unit": "DAY" } } Valid units: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, and EON. For "all time" or "ever" queries (for example, how many users ever did X): { "last": { "value": 1, "unit": "EON" } } The EON unit represents all time from the beginning of data collection. For absolute ranges (for example, January 2024 to January 2025): { "start": "2024-01-01", "end": "2025-01-01" } Date formats accepted: ISO-8601 dates (YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS), dates with timezone (Z or +/- offset), or epoch milliseconds. Dates without timezone are interpreted in the application's configured timezone.

(Optional) time_grain – Overrides the time granularity for the exploration data (for example, daily, weekly, or monthly). The agent should include this parameter when the user specifies a different time grouping than the exploration's default (for example, "show me monthly instead", "break it down by week", "daily granularity"). The object has two fields: { "value": <number>, "unit": "<UNIT>" } Common examples: Daily: { "value": 1, "unit": "DAY" }, Weekly: { "value": 1, "unit": "WEEK" }, Monthly: { "value": 1, "unit": "MONTH" }. Valid units: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.

(Optional) filters – Filter overrides to apply at query time without saving the exploration. Use this for user-selectable dashboard filter tiles when the user specifies a value. Pass column_id and operator from the filter tile response plus the user's value. Also use for ad-hoc filtering outside a dashboard context. Do not use this for always-on filter tiles. Pass dashboard_id instead and the backend auto-applies them. Multiple filters are combined with and logic. Each filter object has teh following:

column_id – An entity reference object with entity_id (string). The entity_id is the id field from an entity returned by the oa_find_entities tool, and an optional field_path (string) that targets a JSON subfield using dot notation (for example, "plan.name" or "revenue"). Use field_path only when the entity is a JSON-typed column whose subfields you discovered with the oa_find_entities tool. Examples: {"entity_id": "433243659_b9115050-f9db-4564-8378-220c7a51d5d3"}, {"entity_id": "433243659_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "field_path": "plan.name"}

operator (string) – One of EQUAL, NOT_EQUAL, IN, NOT_IN, CONTAINS, NOT_CONTAINS, LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, or STARTS_WITH.

value (string) – Required for all operators except IN and NOT_IN.

values (array of strings) – For IN and NOT_IN only. For example, ["Web", "iOS"]. Use instead of value.

(Optional) negate (boolean) – Inverts the filter, defaults to false.

(Optional) dashboard_id – When analyzing an exploration in the context of a dashboard, pass the dashboard ID here (format: <number>_<uuid>). The backend automatically applies any always-on filter tiles (those with a non-null default_value) at query time without saving. Get this from the oa_explores_for_dashboard tool. For user-selectable filter tiles, use filters instead. Do not pass explore IDs or experiment IDs here.

(Optional) sampling – Override the sampling configuration for this query. Use this when you want to change sampling behavior (for example, remove sampling and rerun this query, disable sampling, or use faster sampling). The sampling object controls data sampling for query performance. It has the following fields:

mode (string) – One of the following:

FAST – Quick sampling.

PRECISE – Higher accuracy sampling.

DISABLED – No sampling, full scan.

PRESET – Use a preset sampling rate, 0-6.

CUSTOM – Specify exact percentage.

(Optional) preset (integer) – For PRESET mode, a value from 0 to 6 where 0 or 1 yields 1% sample, and 2-6 yields 2^(preset-1) percent (for example, preset 6 = 32% sample.

(Optional) rate (number) – For CUSTOM mode, the percentage to sample expressed as a whole number (for example, 5.0 means 5% sample)

(Optional) confidence (number) – Statistical confidence level, currently not used.

(Optional) error (number) – Acceptable error margin, currently not used.

Example prompts

Analyze the "Signup Funnel" exploration for the last 30 days.

Re-run the "Weekly Active Users" exploration with monthly granularity instead.

Show me the results of the "Revenue by Region" exploration with sampling disabled.

Analyze the "Checkout Conversion" exploration from the marketing dashboard, filtered to iOS users only.

When to use

Create a new scorecard for an experiment that does not have one yet.

Build a custom scorecard with specific metrics for an existing experiment.

Generate a scorecard that can be analyzed or added to an experiment's Explore tab.

Scope a scorecard to a specific cohort or breakdown dimension.

Parameters

metrics – The metrics to track on the scorecard. This is a list of metric IDs obtained from the oa_find_metrics. tool Each metric ID corresponds to a saved metric entity. At least one metric is required. For example, ["metric-id-1", "metric-id-2"].

experiment – The experiment to create a scorecard for. Can be either the experiment ID (from the oa_find_experiments tool) or the experiment name. If a name is provided, it will be fuzzy-matched to find the experiment.

(Optional) appid – The ID of your Optimizely Analytics application for context. Opal uses the appid from your system context if available, or explicitly asks you for this value. You can often find it in the URL of your Optimizely Analytics project (signified by ?app=).

(Optional) filters – Filters to apply to the scorecard to narrow the population. Each filter object has: column_id (an entity reference), operator, and value or values. Multiple filters are combined with AND logic.

(Optional) actor_dataset – The id field from the dataset object returned by oa_find_datasets. Determines which actor dataset defines the unit of analysis for unique counts.

(Optional) group_by – A breakdown dimension (entity ID from the oa_find_entities tool). When provided, results are grouped by this dimension (for example, platform, country, and user segment).

(Optional) cohort – A cohort ID to apply to the scorecard. Use the oa_find_cohorts tool to discover available cohorts. When specified, the scorecard only includes users in this cohort.

Example prompts

Create a scorecard for the "Homepage Redesign" experiment using the "Conversion Rate" and "Revenue per Visitor" metrics.

Build a scorecard for experiment exp-123 with the "Add to Cart" metric, broken down by country.

Create a custom scorecard for the "Checkout Flow" experiment scoped to the "Premium Users" cohort.

When to use

Analyze what drives or causes a specific outcome. For example, what causes users to purchase?

Discover the effects of a target behavior. For example, what happens after users sign up?

Reveal temporal relationships between events, cohort membership, or metrics.

Identify the most influential behaviors or properties leading to a conversion event.

Parameters

direction – Analysis direction. Can be one of the following:

CAUSES – Find what causes the target. Test behaviors happen before target.

EFFECTS – Find effects of the target. Test behaviors happen after target.

target_behavior – The behavior to analyze. Must have a type field (DID_EVENT, IN_COHORT, or METRIC) and corresponding data.

For DID_EVENT – Include event with dataset_id, event_names, and optional name.

For IN_COHORT – Include cohort with type (ACTOR_DATASET or COLLECTION) and either actor_dataset_id or collection.

For METRIC – Include metric with the metric ID.

test_behaviors – The behaviors to test for influence. Must have a type field (DID_EVENT, IN_COHORT, or METRIC) and corresponding data.

For DID_EVENT – Include event and test_property.

For IN_COHORT – Include cohorts array.

For METRIC – Include metrics array.

name – A concise, descriptive name for the exploration, intelligently generated by the agent.

time_window – Time window for the temporal relationship. Must have value (integer) and unit (SECOND, MINUTE, HOUR, DAY, WEEK, or MONTH).

(Optional) description – A brief description of what the exploration analyzes, intelligently generated by the agent.

(Optional) time_range – Specifies the time range for the analysis. The object must have either a last field for relative ranges or both start and end fields for absolute ranges.

(Optional) time_grain – Specifies the granularity for time-series data. The object has two fields: value (number) and unit (SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR).

(Optional) actor_dataset – The id field from the dataset object returned by the oa_find_datasets tool. Determines which actor dataset defines the unit of analysis for unique counts. For example, users, accounts, subscriptions, and devices. If not provided, Opal uses the app's default actor dataset.

(Optional) filters – A list of filters to apply to the exploration. Each filter object has the following: column_id (an entity reference), operator, and value or values. Multiple filters are combined with and logic.

(Optional) top_n – Limit results to top N most influential items.

(Optional) chart_config – Chart visualization configuration.

(Optional) appid – The ID of your Optimizely Analytics application for context. Opal uses the appid from your system context if available, or explicitly asks you for this value. You can often find it in the URL of your Optimizely Analytics project (signified by ?app=).

Example prompts

What causes users to complete a purchase within 7 days?

Show me what influences churn. What behaviors happen before users cancel their subscription?

What do users do after signing up? Show me the effects within 30 days.

Which events are most influential in driving the "add to cart" event?

When to use

Discover what paths users take before or after a key event. For example, What do users do in the three steps before checkout?

Visualize user journey sequences as a Sankey diagram or table.

Identify common navigation patterns and drop-off points in a user flow.

Understand the sequence of actions leading to or following a conversion event.

Parameters

name – A concise, descriptive name for the exploration, intelligently generated by the agent.

events – A list of event groups that define the user journey. Each object must have the following three fields:

name – A descriptive label.

dataset_id – The datasetId from JoinableEvent objects. must be the same across all groups.

event_names – Array of event name strings from the oa_find_events tool.

focal_event – The name of the event that serves as the focal point of the journey. This must be one of the event names from the events parameter. The path analysis displays what happens before and after this focal event occurs.

steps – Specifies how many steps to show before and after the focal event. Must have before (integer, default 0) and after (integer, default 5) fields. The sum of before + after must be greater than 0. For example, {"before": 2, "after": 3} displays two steps before and three steps after the focal event.

description – A brief, one-sentence description of what the exploration shows, intelligently generated by the agent.

(Optional) appid – The ID of your Optimizely Analytics application for context. Opal uses the appid from your system context if available, or explicitly asks you for this value. You can often find it in the URL of your Optimizely Analytics project (signified by ?app=).

(Optional) time_range – Specifies the time range for the exploration. Accepts relative ranges (for example, last 30 days) or absolute ranges (for example, January 2024 to January 2025).

(Optional) time_grain – Specifies the granularity for time-series data (for example, daily, weekly, or monthly).

(Optional) actor_dataset – The id field from the dataset object returned by the oa_find_datasets tool. Determines which actor dataset defines the unit of analysis for unique counts.

(Optional) filters – A list of filters to apply to the exploration. Each filter narrows results to rows where the column matches the given value.

(Optional) group_by – One or more entity references (from the oa_find_entities tool) to group the results by.

(Optional) top_n – Maximum number of unique values to show in each step of the path. Defaults to 5. Use this to limit the complexity of the path visualization.

(Optional) ignore_repeats – Whether to collapse adjacent identical events into a single node in the path. Defaults to false. Set to true to simplify paths where users repeat the same action.

(Optional) measure – The measure type. Currently only UNIQUES_CONVERTED (counts unique actors who took the path) is supported. This is the default value.

(Optional) chart_config – Chart visualization configuration. For path analysis, the default is a SANKEY diagram. Use this to specify alternative visualizations like {"subType": "TABLE"} to display results as a table.

Example prompts

What do users do in the 3 steps before checkout?

Show me the user journey after the "sign up" event and 5 steps forward.

Create a path analysis showing 2 steps before and 3 steps after the "add to cart" event for the last 30 days.

What paths do users take before reaching the pricing page? Collapse repeated events.

When to use

After you have identified the necessary events using oa_find_events.

After you have identified any entities for grouping using oa_find_entities.

When you are ready to finalize and save an exploration.

Parameters

appid – The ID of your Optimizely Analytics application for context. Opal uses the appid from your system context if available, or explicitly asks you for this value. You can often find it in the URL of your Optimizely Analytics project (signified by ?app=).

explore_type – Specifies the type of exploration to create. Available values are FUNNEL_BLOQ, RETENTION, or EVENT_SEGMENT.

events – A list of event groups that define the exploration.

For Funnels, the order of events in this list defines the stage order.

For Retention, this list must contain exactly two event groups: the first is the 'initial' event group, and the second is the 'return' event group.

For Event Segmentation, this list must contain exactly one event group.

Each event group must contain JoinableEvent objects obtained from the oa_find_events tool.

(Optional) name – A concise, descriptive name for your exploration. Opal intelligently generates this, but if there is a duplicate name, Opal asks you for a new one.

(Optional) description – A brief, one-sentence description of what the exploration shows. Opal intelligently generates one, if you do not provide one.

(Optional) group_by – The id from a JoinableEntity object (returned by the oa_find_entities tool) to group the results. Used when you explicitly request to 'group by' or 'break down by' a specific attribute.

(Required for EVENT_SEGMENT) measure – The metric to measure for Event Segmentation. Available values are EVENT_COUNT, UNIQUE_ACTOR_COUNT, or AVG_EVENT_BY_ACTOR.

Example prompts

Create a funnel exploration for users who viewed a product page and then added an item to their cart.

Show me the retention of users who signed up and then returned to make a purchase.

Create an event segmentation report for all 'click' events, grouped by device type.

I want a funnel that tracks 'page_view' of the homepage, followed by 'add_to_cart', and then 'purchase'.

Generate a retention report for users who 'signed_up' and then 'logged_in'.

When to use

Aggregate a numeric column from a dataset table, for example, total revenue or average subscription value.

Count distinct values in a column to understand how many unique entities exist, such as distinct account types.

Track how a column aggregation changes over time by enabling a time-series view.

Break down a dataset metric by a specific attribute, for example, total revenue grouped by plan name.

Run multiple aggregations in a single exploration, for example, SUM and AVG of the same column simultaneously.

Parameters

name – A concise, descriptive name for the exploration, intelligently generated by the agent.

description – A brief, one-sentence description of what the exploration shows, intelligently generated by the agent.

measures – A list of measures to compute. At least one measure is required. Each measure object must have the following fields:

type (string) – Must be COLUMN_AGGREGATION for this tool.

aggregation (string) – The aggregation function. One of the following:

COUNT_DISTINCT – Count unique values.

SUM – Sum of values.

AVG – Average.

MIN – Minimum.

MAX – Maximum.

COUNT – Count all rows.

column_id – An entity reference for the column with the following information:

entity_id (string) – The id field from an entity returned by the oa_find_entities tool.

(Optional) field_path (string) – Targets a JSON subfield using dot notation (for example, plan.name or revenue). Use field_path only when the entity is a JSON-typed column whose subfields you discovered using the oa_find_entities tool.

(Optional) name (string) – Display name for the measure. If not provided, a default name will be generated.

(Optional) appid – The ID of your Optimizely Analytics application for context. Opal uses the appid from your system context if available, or explicitly asks you for this value. You can often find it in the URL of your Optimizely Analytics project (signified by ?app=).

(Optional) actor_dataset – The id field from the dataset object returned by the oa_find_datasets tool. Determines which actor dataset defines the unit of analysis for unique counts (for example, users, accounts, subscriptions, and devices). If not provided, Opal uses the app's default actor dataset.

(Optional) attributes – One or more entity references (from the oa_find_entities tool) to group the results by. Each element is an entity reference with the following:

entity_id (string) – The id field from an entity returned by oa_find_entities.

(Optional) field_path (string) – Targets a JSON subfield using dot notation (for example, plan.name or revenue). Use field_path only when the entity is a JSON-typed column whose subfields you discovered using the oa_find_entities tool.

(Optional) filters – A list of filters to apply to the exploration. Multiple filters are combined with and logic. Each filter object has the following:

column_id – An entity reference with the following:

entity_id (string) – The id field from an entity returned by the oa_find_entities tool.

(Optional) field_path (string) – Targets a JSON subfield using dot notation (for example, plan.name or revenue). Use field_path only when the entity is a JSON-typed column whose subfields you discovered through the oa_find_entitie tool.

operator (string) – One of EQUAL, NOT_EQUAL, IN, NOT_IN, CONTAINS, NOT_CONTAINS, LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STARTS_WITH.

value (string) – Required for all operators except IN and NOT_IN.

values (array of strings) – For IN and NOT_IN only (for example, ["Web", "iOS"]), use instead of value.

(Optional) negate (boolean) – Inverts the filter, defaults to false.

(Optional) show_over_time – Controls whether results are shown as a time series or as a single aggregate value. Defaults to true.

(Optional) time_range – Filters data to a specific time window. The object must have either a last field for relative rangeso4R both start and end fields for absolute ranges.

(Optional) chart_config – Chart visualization configuration. Common use: set {"subType": "TABLE"} to display results as a table. Other valid subTypes include LINE, BAR, PIE, and HEADLINE.

Example prompts

Show total revenue aggregated from the subscriptions table for the last 30 days, broken down by plan name.

How many distinct account types exist in the accounts dataset? Show it as a single number, not over time.

Create an exploration that sums revenue and counts distinct customers from the orders table over the past three months, grouped by week.

Aggregate the average order value from the purchases dataset, filtered to include only orders from the US.

Show me the maximum and minimum subscription price from the subscriptions table as a table visualization.

Experiment management tools

Note

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applicationsTurn generative AI off across Optimizely applications.

System tools for Optimizely Analytics

Dashboard management tools

oa_find_dashboards – Searches for dashboards in Optimizely Analytics using fuzzy search on dashboard names and semantic search on descriptions.

oa_create_dashboard – Creates a new empty dashboard in Optimizely Analytics.

oa_add_explore_to_dashboard – Adds an existing exploration as a tile to a dashboard in Optimizely Analytics.

oa_add_text_tile_to_dashboard – Adds a text or header tile to a dashboard in Optimizely Analytics.

oa_add_image_tile_to_dashboard – Adds an image tile to a dashboard by downloading an image from a URL in Optimizely Analytics.

oa_arrange_dashboard_tiles – Repositions and resizes tiles on a dashboard using a 24-column grid layout in Optimizely Analytics.

oa_explores_for_dashboard – Retrieves all explorations and filter tiles contained within a specific dashboard in Optimizely Analytics.

oa_revert_dashboard_layout – Reverts a dashboard layout to its previous state in Optimizely Analytics.

Data retrieval and app configuration tools

oa_confirm_app – Confirms your app selection for the current Optimizely Analytics session.

oa_find_cohorts – Finds and lists saved cohorts (also called saved audiences or user segments) in Optimizely Analytics.

oa_find_column_values – Fetches distinct real values for a specific column or property in Optimizely Analytics.

oa_find_datasets – Searches and lists available datasets in Optimizely Analytics. It uses fuzzy matching on dataset names and semantic search on descriptions to find relevant datasets.

oa_find_metrics – Searches for saved metrics in Optimizely Analytics using fuzzy search on metric names and semantic search on descriptions.

oa_get_metric_data – Retrieves and executes a specific saved metric in Optimizely Analytics, returning its calculated table data.

oa_list_apps – Lists all available applications in Optimizely Analytics.

oa_list_categories – Lists all categories available in the current Optimizely Analytics application.

Data ingestion tools

oa_csv_upload – Uploads Comma-Separated Values (CSV) data into a new or existing table in the app's data warehouse in Optimizely Analytics.

Exploration creation tools

oa_analyze_explore – Retrieves exploration data from Optimizely Analytics for analysis of existing saved explorations.

oa_create_experiment_scorecard – Creates an experiment scorecard exploration with specified metrics and configuration in Optimizely Analytics.

oa_create_exploration_influence – Creates an influence analysis exploration to find what causes or is caused by a target behavior in Optimizely Analytics.

oa_create_exploration_paths – Creates a Path Analysis exploration in Optimizely Analytics to visualize user journeys before and after a focal event.

oa_create_explore – Constructs and saves a FunnelFunnel, RetentionRetention, or Event SegmentationEvent Segmentation exploration in Optimizely Analytics.

oa_create_universal_explore – Creates a Universal exploration to analyze dataset tables by aggregating column values in Optimizely Analytics.

oa_find_entities – Searches for analytics entities (also known as properties or attributes) based on a natural language query within Optimizely Analytics.

oa_find_events – Searches for and returns a list of analytics events based on a natural language query.

oa_find_explores – Helps you find existing saved explorations in Optimizely Analytics by using AI to understand your request and find relevant explorations even if your wording is slightly different from the saved name.

Experiment management tools

oa_add_explore_to_experiment – Adds an existing exploration to an experiment's Explore Tab in Optimizely Analytics.

oa_analyze_experiment – Fetches and analyzes the Summary (scorecard) tab for an Optimizely experiment.

oa_experiment_explore_tab – Lists the explorations in an experiment's Explore tab in Optimizely Analytics.

oa_find_experiments – Searches for Optimizely experiments by name in Optimizely Analytics.