System tools for Optimizely Analytics

  • Updated

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 Analytics provides system tools to help you with Analytics-related tasks, in addition to the system tools already available in Opal.

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

oa_find_dashboards – Searches for dashboards in Optimizely Analytics using fuzzy search on dashboard names and semantic search on descriptions.
  • When to use
    • Find, search for, or list dashboards in Optimizely Analytics. For example, find dashboards, search for marketing dashboard, show me available dashboards.
    • Locate a specific dashboard by name before adding explorations to it or analyzing its contents.
    • Get an overview of all available dashboards and their descriptions.
  • Parameters
    • query – A natural language search query to find dashboards. For example, marketing overview, sales performance, or user engagement. The search uses fuzzy matching on names and semantic matching on descriptions.
    • (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) categories – A list of category IDs to filter results by. When provided, only results that belong to at least one of the specified categories will be returned. Use the oa_list_categories tool to discover available categories and their IDs. Category filtering is handled entirely by this parameter. Do not include category names or references to categories in the query parameter. If the request is solely about filtering by category, use a broad query such as an empty string.
  • Example prompts
    • Find dashboards related to "marketing overview".
    • Show me all available dashboards.
    • Search for a dashboard called "Q4 Sales Performance".
oa_create_dashboard – Creates a new empty dashboard in Optimizely Analytics.
  • When to use
    • Create a new dashboard to organize explorations and visualizations together.
    • Set up a centralized reporting view before adding exploration tiles.
    • Build a custom dashboard for a specific project, team, or campaign.
  • Parameters
    • name – A concise, descriptive name for the dashboard, 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) description – A brief description of what the dashboard displays, intelligently generated by the agent.
  • Example prompts
    • Create a new dashboard for our Q1 marketing campaign.
    • Set up a dashboard called "User Engagement Overview".
    • I need a new dashboard to track our conversion funnel metrics.
oa_add_explore_to_dashboard – Adds an existing exploration as a tile to a dashboard in Optimizely Analytics.
  • When to use
    • Add a saved or newly created exploration to an existing dashboard for centralized reporting.
    • Build a custom dashboard by adding multiple explorations as tiles.
    • Attach a funnel, retention, or segmentation analysis to a dashboard after creating it.
  • Parameters
    • explore_id – The unique identifier of the exploration to add (format: <number>_<uuid>). The source determines which field to use. For saved explores from oa_find_explores, use the id field directly. For draft explores from oa_create_explore, use the explore.draftId field (not explore.id). Do not pass dashboard IDs or experiment IDs here.
    • dashboard_id – The unique identifier of the dashboard (format: <number>_<uuid>). Must be obtained from the oa_find_dashboards or oa_create_dashboard tools. This is a dashboard entity ID only. Do not pass experiment IDs, explore IDs, or any other entity type here. Doing so causes an error. If you have an experiment and need its Explore tab dashboard, use the explores_dashboard_id field from the oa_find_experiments tool instead.
    • (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) tile_name – A display name for the tile on the dashboard. If omitted, the exploration's name is used automatically.
  • Example prompts
    • Add the exploration I just created to my "Marketing Overview" dashboard.
    • Put the "Signup Funnel" exploration on my Q4 dashboard.
    • Add explore explore-123 to dashboard dashboard-456 with the tile name "Weekly Conversions".
oa_add_text_tile_to_dashboard – Adds a text or header tile to a dashboard in Optimizely Analytics.
  • When to use
    • Create section headers or titles on a dashboard to organize content visually.
    • Add descriptive text or annotations alongside data tiles on a dashboard.
    • Label groups of explorations within a dashboard layout.
  • Parameters
    • dashboard_id – The unique identifier of the dashboard (format: <number>_<uuid>). Must be obtained from oa_find_dashboards or oa_create_dashboard. This is a dashboard entity ID only. Do not pass experiment IDs, explore IDs, or any other entity type here — doing so will cause an error. If you have an experiment and need its Explore tab dashboard, use the explores_dashboard_id field from the oa_find_experiments tool instead.
    • text – The text content to display in the tile.
    • (Optional) format – The text format or style: h1 (large heading), h2 (medium heading, default), h3 (small heading), or body (paragraph text).
    • (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
    • Add a heading "Conversion Metrics" to my marketing dashboard.
    • Put a large title tile saying "Q1 2026 Performance" on my dashboard.
    • Add a body text tile with a description of the dashboard's purpose.
oa_add_image_tile_to_dashboard – Adds an image tile to a dashboard by downloading an image from a URL in Optimizely Analytics.
  • When to use
    • Display screenshots, logos, or pictographic elements alongside metrics and data on a dashboard.
    • Add generated visualizations or infographics to a dashboard.
    • Include brand imagery or contextual photos on a reporting dashboard.
  • Parameters
    • dashboard_id – The unique identifier of the dashboard to add the image tile to. Obtained from the oa_create_dashboard or oa_find_dashboards tools.
    • image_url – The URL of the image to download and add to the dashboard. Must be a publicly accessible URL pointing to an image file (.jpg, .png, .gif, or .webp). The image is downloaded, validated, and stored automatically. Maximum file size: 10MB.
    • (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) title – The title displayed above the image.
    • (Optional) caption – A caption or description displayed with the image.
    • (Optional) height – The tile height in dashboard grid units (default: 8, where each unit is 25 pixels). Width is determined by the dashboard grid layout and maintains the image aspect ratio based on object_fit. The tile will be appended to the bottom of the dashboard. Useful for tall images like infographics or compact images like logos.
    • (Optional) object_fit – How the image fits within the tile. If not provided, front end applies default styling. Can be one of the following:
      • COVER – Fills tile and crops excess.
      • CONTAIN – Fits inside tile maintaining aspect ratio.
      • FILL – Stretches to fill tile.
  • Example prompts
    • Add an image from https://example.com/chart.png to my marketing dashboard.
    • Put our company logo on the "Q1 Report" dashboard with the title "Brand Header".
    • Add an infographic to my dashboard with a height of 12 grid units and use CONTAIN fit.
oa_arrange_dashboard_tiles – Repositions and resizes tiles on a dashboard using a 24-column grid layout in Optimizely Analytics.
  • When to use
    • Organize tiles into a visually appealing layout after adding explorations, text, or images to a dashboard.
    • Resize tiles to give more or less space to specific explorations on a dashboard.
    • Reposition tiles to create a structured, multi-row dashboard layout.
  • Parameters
    • tiles – A list of tile layout objects. All tiles on the dashboard must be included. Each object must have the following: 
      • tile_id (string) – The tile ID from the oa_add_explore_to_dashboard or oa_explores_for_dashboard tools.
      • x (integer) – Column start position (0–23).
      • y (integer) – Row start position (0+).
      • w (integer) – Width in columns (1–24).
      • h (integer) – Height in rows (typically 6–10 for explore tiles, 2–3 for text tiles). 
    • dashboard_id – The unique identifier of the dashboard (format: <number>_<uuid>). Must be obtained from the oa_find_dashboards or oa_create_dashboard tools. This is a dashboard entity ID only. Do not pass experiment IDs, explore IDs, or any other entity type here. Doing so causes an error. If you have an experiment and need its Explore tab dashboard, use the explores_dashboard_id field from the oa_find_experiments tool instead.
    • (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
    • Arrange the tiles on my dashboard so the funnel is on top and the segmentation is below it.
    • Make all the tiles on my dashboard take up half the width, side by side.
    • Reorganize my dashboard tiles into a 2-column layout.
oa_explores_for_dashboard – Retrieves all explorations and filter tiles contained within a specific dashboard in Optimizely Analytics.
  • When to use
    • See what explorations are on a dashboard before analyzing or modifying it.
    • Discover the filter tiles applied to a dashboard so you can analyze explorations with the correct context.
    • Get the tile IDs for dashboard tiles so you can rearrange them.
  • Parameters
    • dashboard_id – The unique identifier of the dashboard (format: <number>_<uuid>). Must be obtained from the oa_find_dashboards or oa_create_dashboard tools. This is a dashboard entity ID only. Do not pass experiment IDs, explore IDs, or any other entity type here. Doing so causes an error. If you have an experiment and need its Explore tab dashboard, use the explores_dashboard_id field from the oa_find_experiments tool instead.
    • (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 explorations are on my "Marketing Overview" dashboard?
    • Show me the contents of the "User Engagement" dashboard.
    • List all the tiles on my Q4 dashboard.
oa_revert_dashboard_layout – Reverts a dashboard layout to its previous state in Optimizely Analytics.
  • When to use
    • Undo the last tile arrangement on a dashboard and restore the previous layout.
    • Revert an accidental or undesirable dashboard layout change.
    • Restore a dashboard's tile positions after experimenting with different arrangements.
  • Parameters
    • tiles – The previous_layout value returned by the oa_arrange_dashboard_tiles tool. Contains the full tile position snapshot (tile_id, x, y, w, and h) before the last arrange. Pass this array directly as tiles to restore the previous layout.
    • dashboard_id – The unique identifier of the dashboard (format: <number>_<uuid>). Must be obtained from the oa_find_dashboards or oa_create_dashboard tools. This is a dashboard entity ID only. Do not pass experiment IDs, explore IDs, or any other entity type here. Doing so causes an error. If you have an experiment and need its Explore tab dashboard, use the explores_dashboard_id field from the oa_find_experiments tool instead.
    • (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
    • Undo the last layout change on my dashboard.
    • Revert the dashboard tile arrangement to how it was before.
    • The new layout doesn't look right — restore the previous one.

Data retrieval and app configuration tools

oa_confirm_app – Confirms your app selection for the current Optimizely Analytics session.
  • When to use
    • Confirm an app selection after you picks one from the oa_list_apps list.
    • Switch to a different app when oa_list_apps auto-resolved an app but you hinted at a different one.
    • Set or remove a default app for future sessions when you explicitly request it.
  • Parameters
    • appid – The UUID of the selected app, taken from the hidden appid field in the oa_list_apps tools response. This must be the UUID value (for example, 2705840d-23ca-404a-9c23-207dd31af320), not the app name.
    • (Optional) set_as_default – Controls your default app preference: 
      • true saves this app as your default for future sessions. 
      • false removes this app as your default (if it is currently the default).
  • Example prompts
    • Use the "Production" app for this session.
    • Set my default app to "Marketing Analytics".
    • Remove my default app setting.
oa_find_cohorts – Finds and lists saved cohorts (also called saved audiences or user segments) in Optimizely Analytics.
  • When to use
    • Find, list, or discover existing cohorts, audiences, or segments in Optimizely Analytics.
    • See what saved audiences are available for use in explorations or scorecards.
    • Search for specific user groups like VIP users, premium customers, or churned users.
    • Browse all available cohorts when no specific query is needed.
  • Parameters
    • (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) query – A natural language description or name of the cohort to search for. For example,"premium users" or VIP. If not provided, returns all cohorts.
    • (Optional) limit – Maximum number of cohorts to return (default 100).
  • Example prompts
    • Show me all available cohorts.
    • Find cohorts related to "premium customers".
    • List saved audiences that match "churned users".
    • What user segments are available in my analytics app?
oa_find_column_values – Fetches distinct real values for a specific column or property in Optimizely Analytics.
  • When to use
    • Discover what values exist in a column before using them in a filter (for example, if the column is Company, this returns values like Canva Pty Ltd, Google, and Stripe).
    • Verify the exact stored value for your filter input, since filter values are case-sensitive.
    • Search for specific column values by a partial string match.
  • Parameters
    • column_id – The column reference to fetch values for. An entity reference object 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 using the oa_find_entities tool.
    • (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) search_str – A search string to filter the returned values.
  • Example prompts
    • What values exist in the "country" column?
    • Show me all distinct values for the "plan type" property.
    • Search for column values that start with "US" in the region field.
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.
  • When to use
    • To locate specific datasets by name or keyword within Optimizely Analytics.
    • To discover available datasets related to a particular topic or area of interest.
    • To get a comprehensive list of all accessible datasets.
    • To identify relevant datasets for further analysis or reporting.
  • Parameters
    • query – A natural language search query to filter datasets by name or description. For example, mobile users, premium customers, or active subscribers.
    • (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) categories – A list of category IDs to filter results by. Use the  Use the oa_list_categories tool to discover available categories.
  • Example prompts
    • Find datasets related to 'user behavior'.
    • Show me all datasets.
    • What datasets can I use for my analysis?
    • Are there any datasets about 'e-commerce sales'?
    • Search for datasets containing 'product'.
oa_find_metrics – Searches for saved metrics in Optimizely Analytics using fuzzy search on metric names and semantic search on descriptions.
  • When to use
    • Locate a previously saved metric, like revenue or conversion rate, for use in an exploration or scorecard.
    • Search for existing metrics by name or description to reference in an experiment scorecard.
    • Discover available metrics related to a specific business area, such as average order value or bounce rate.
  • Parameters
    • query – A natural language search query to find metrics (for example, revenue, conversion rate, or average order value). The search uses fuzzy matching on names and semantic matching on descriptions.
    • (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) categories – A list of category IDs to filter results by. When provided, only results that belong to at least one of the specified categories will be returned. Use the oa_list_categories tool to discover available categories and their IDs. Category filtering is handled entirely by this parameter. Do not include category names or references to categories in the query parameter. If the request is solely about filtering by category, use a broad query such as an empty string.
  • Example prompts
    • Are there any saved metrics for conversion rate?
    • Show me metrics related to average order value.
    • Can you find the "daily active users" metric?
    • Search for metrics about revenue or purchases.
oa_get_metric_data – Retrieves and executes a specific saved metric in Optimizely Analytics, returning its calculated table data.
  • When to use
    • You want to see the actual data values for a metric you previously found using the oa_find_metrics tool. 
    • To analyze the trends or patterns for a specific metric over a defined period or granularity.
    • You want to understand the performance of a key business indicator. 
  • Parameters
    • app_id – 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=).
    • metric_id – The ID of the specific metric to retrieve from the oa_find_metrics tool.
    • (Optional) start_date – The start date for the data retrieval in 'YYYY-MM-DD' format. 
    • (Optional) end_date – The end date for the data retrieval in 'YYYY-MM-DD' format.
  • Example prompts
    • Get metric data for app 123 and metric conversion_rate.
    • Retrieve the page_views metric for application 456 from 2025-01-01 to 2025-01-31.
    • What is the bounce_rate for app 789?
    • Show me the revenue metric for app 101 for the last week.
oa_list_apps – Lists all available applications in Optimizely Analytics.
  • When to use
    • To see all applications you have access to within Analytics.
    • To find the ID of a specific application when you need to perform actions on it.
    • To get an overview of your Optimizely Analytics application landscape and available projects.
  • Parameters
    • None
  • Example prompts
    • List all Optimizely applications.
    • What applications are available in Optimizely Analytics?
    • Show me a list of all apps I have access to.
oa_list_categories – Lists all categories available in the current Optimizely Analytics application.
  • When to use
    • Discover available category IDs for use with the categories filter parameter in other search tools.
    • Filter search results for events, entities, datasets, explores, metrics, or dashboards by category.
    • Browse all categories to understand how your analytics data is organized.
  • Parameters
    • (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 categories are available in my analytics app?
    • List all categories so I can filter my event search.
    • Show me the category IDs I can use to filter explorations.

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.
  • When to use
    • Upload CSV content or load tabular data into the Optimizely Analytics data warehouse.
    • Create a new table from a CSV file for use in explorations and analyses.
    • Append new rows to an existing warehouse table or overwrite it with fresh data.
  • Parameters
    • columns – Array of column definitions. Each element must have name (string) and type (one of: BOOL, DATE, DATETIME, DOUBLE, INT32, INT64, TIME, or VARCHAR).
    • table_name – The name for the destination table.
    • (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) csv_data – The CSV file content, base64-encoded. Provide either csv_data or file_url. Maximum decoded size is 5 MB.
    • (Optional) file_url – URL of a CSV file to download. The file is fetched using the caller's access token. Provide either file_url or csv_data. Maximum file size is 20 MB.
    • (Optional) write_mode – How to handle existing data. Defaults to CREATE.
    • (Optional) has_header – Whether the first row of the CSV is a header row. If true, the header row is skipped during data loading. Defaults to true.
  • Example prompts
    • Upload this CSV file to a new table called "campaign_results" with columns: name (VARCHAR), revenue (DOUBLE), date (DATE).
    • Load the CSV at https://example.com/data.csv into the warehouse as "user_events".
    • Overwrite the existing "orders" table with new data from my CSV.
    • Append rows from this CSV to the "daily_metrics" table.

Exploration creation tools

oa_analyze_explore – Retrieves exploration data from Optimizely Analytics for analysis of existing saved explorations.
  • 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.
oa_create_experiment_scorecard – Creates an experiment scorecard exploration with specified metrics and configuration in Optimizely Analytics.
  • 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.
oa_create_exploration_influence – Creates an influence analysis exploration to find what causes or is caused by a target behavior in Optimizely Analytics.
  • 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?
oa_create_exploration_paths – Creates a Path Analysis exploration in Optimizely Analytics to visualize user journeys before and after a focal 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.
oa_create_explore – Constructs and saves a Funnel, Retention, or Event Segmentation exploration in Optimizely Analytics.
  • 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'.
oa_create_universal_explore – Creates a Universal exploration to analyze dataset tables by aggregating column values in Optimizely Analytics.
  • 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.
oa_find_entities – Searches for analytics entities (also known as properties or attributes) based on a natural language query within Optimizely Analytics.
  • When to use
    • Find specific properties that you want to use for analysis.
    • Identify properties to "group by," "break down by," or analyze "for each" when creating an exploration.
    • Discover properties related to a specific event that you have already identified using oa_find_events.
  • 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=).
    • query – A natural language description of the property you are searching for (for example, "country" or "device type").
    • (Optional) event – A JoinableEvent object (returned from the oa_find_events tool) to restrict the search to entities related to that specific event. 
    • (Optional) categories – A list of category IDs to filter results by.
  • Example prompts
    • Find entities related to "country" or "device type."
    • What properties can I use to group my 'purchase' events?
    • Show me the entities associated with the 'user signed up' event.
    • I want to break down my funnel by "browser type." 
oa_find_events – Searches for and returns a list of analytics events based on a natural language query.
  • When to use
    • When you need to identify specific user actions, such as 'user signed up' or 'product added to cart'.
    • As the initial step in building an analytics exploration, as its output is required by the oa_create_explore tool.
    • To find events that Opal can use to discover related properties with the oa_find_entities tool.
    • Find the correct event objects to use as stages in a funnel, initial or return events in a retention report, or events to segment in an event segmentation report.
  • Parameters 
    • query – A natural language description of the event you are searching for (for example, "user signed up").
    • (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 a dataset object returned by `oa_find_datasets` to filter events to only those that can be joined from this actor dataset.
    • (Optional) categories – A list of category IDs to filter results by.
  • Example prompts
    • Find the event for "user signed up."
    • What are the events related to "product added to cart"?
    • Show me the event for when a user "completed checkout."
    • I need to find events for "page view" and "button click."
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.
  • When to use

    • You want to locate a previously saved analysis, like a "signup funnel" or "user retention" report.

    • You are looking for an existing exploration to analyze further.

  • Parameters
    • query – A natural language description of the event you are searching for (for example, "user signed up").
    • (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) categories – A list of category IDs to filter results by.
  • Example prompts

    • Find my 'signup funnel' exploration.

    • Are there any saved explorations about user retention?

    • Show me explorations related to conversion analysis.

    • Can you find the 'Q4 marketing campaign' exploration?

Experiment management tools

oa_add_explore_to_experiment – Adds an existing exploration to an experiment's Explore Tab in Optimizely Analytics.
  • When to use
    • Add a scorecard or exploration to an experiment's Explore tab for supplementary analysis.
    • Attach a saved exploration to an experiment so teams can view it alongside experiment results.
    • Add a newly created scorecard (from the oa_create_experiment_scorecard tool) to an experiment.
    • Enrich an experiment's Explore tab with custom analyses that explain why results occurred.
  • Parameters
    • explore_id – The unique identifier of the exploration to add. For scorecards from the oa_create_experiment_scorecard tool, use the explore_id field from the response. For saved explores from the oa_find_explores tool, use the id field directly.
    • experiment – The experiment to add the explore to. 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) tile_name – A display name for the tile on the experiment's Explore tab. If omitted, the exploration's name is used automatically.
  • Example prompts
    • Add the scorecard I just created to the "Homepage Redesign" experiment.
    • Attach the "Signup Funnel" exploration to my checkout experiment's Explore tab.
    • Add explore explore-456 to experiment exp-123 with the tile name "Revenue Breakdown".
oa_analyze_experiment – Fetches and analyzes the Summary (scorecard) tab for an Optimizely experiment.
  • When to use
    • View and analyze the results of an experiment, including per-variation statistical data.
    • Understand whether an experiment's variations achieved statistical significance.
    • Get a comprehensive analysis of experiment metrics such as conversion rate, revenue, and lift.
  • Parameters
    • scorecard_explore_id – The explore ID of the experiment scorecard (format: <number>_<uuid>). Must be the scorecard_explore_id field from the oa_find_experiments tool's response. This is different from the experiment's own id field. Do not pass the experiment id here. iIt does not work. Always call the oa_find_experiments tool first to obtain this value.
    • (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 the experiment results. Include when you want a specific time period (for example, show me results for the last 30 days. The object must have either a last field for relative ranges or both start and end fields for absolute ranges.
  • Example prompts
    • Analyze the results of the "Homepage Redesign" experiment.
    • Show me the experiment scorecard for the "Checkout Flow" test.
    • What are the results of my latest experiment? Did we reach statistical significance?
oa_experiment_explore_tab – Lists the explorations in an experiment's Explore tab in Optimizely Analytics.
  • When to use
    • View custom analyses attached to an experiment's Explore tab to understand why results occurred.
    • List all explorations scoped to a specific experiment for further analysis.
    • Discover supplementary analyses associated with an experiment before drilling into the data.
  • Parameters
    • explores_dashboard_id – The dashboard ID for the experiment's Explore tab (format: <number>_<uuid>). Must be the explores_dashboard_id field from the oa_find_experiments tool's response. This is a dashboard entity ID scoped to the experiment, not the experiment's own id. If this field is null or missing in the oa_find_experiments response, the experiment has no Explore tab configured.
    • (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
    • Show me the Explore tab for the "Homepage Redesign" experiment.
    • What custom analyses are attached to the "Checkout Flow" experiment?
    • List all explorations on the Explore tab for my latest experiment.
oa_find_experiments – Searches for Optimizely experiments by name in Optimizely Analytics.
  • When to use
    • Locate an experiment by name before analyzing its results or viewing its Explore tab.
    • Look up experiment metadata, including scorecard and Explore tab IDs needed by other tools.
    • List all experiments or search for a specific experiment you want to analyze.
  • Parameters
    • (Optional) query – A natural language search query to find experiments (for example, dragon recommendations, checkout flow test, or homepage redesign). The search uses fuzzy matching on names. Omit or pass an empty string to list all experiments.
    • (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) categories – A list of category IDs to filter results by. When provided, only results that belong to at least one of the specified categories are returned. Use the oa_list_categories tool to discover available categories and their IDs. Category filtering is handled entirely by this parameter. Do not include category names or references to categories in the query parameter. If the request is solely about filtering by category, use a broad query such as an empty string.
  • Example prompts
    • Find the "Homepage Redesign" experiment.
    • List all my experiments.
    • Search for experiments related to "checkout flow".

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