Performance analytics tools

get_discovery_overall_performance: Get the Overall tab metric cards for all site traffic.
get_discovery_search_performance: Get the Site search tab metric cards for search-driven traffic.
get_discovery_category_performance: Get the Category tab metric cards for category-page traffic.
get_discovery_products_overview: Get the Products tab metric cards for product-driven traffic.
get_discovery_trend: Get a daily time series for one metric, with the comparison period alongside it.

get_discovery_overall_performance

Returns the metric cards from the Overall tab of the Performance dashboard, covering all site traffic rather than a single channel. Every metric arrives three ways: the current value, the comparison-period value, and the percent change between them. The backend computes the KPIs, so revenue, revenue per visit, average order value, and conversion rate need no derivation on your side. The metric keys are revenue, rpv, aov, conversion_rate, visits, atc, and conversions.

Date windows anchor to the last date your account has data for, so results match the dashboard's data availability range. By default you get a rolling 30-day window compared against the 30 days immediately before it. Pass start_date with end_date to set an exact current period, and compare_start_date with compare_end_date to choose what it compares against. A date the tool can't parse returns success of False with an Invalid parameter message instead of raising, so read the error field when a call fails. To break the same period down by channel, pair this tool with get_discovery_search_performance, get_discovery_category_performance, and get_discovery_products_overview.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to discover sites.
`days`	`int`	No	The rolling window in days, ending on the last available date. Defaults to `30`. Ignored when you pass an explicit window.
`domain_key`	`str \| null`	No	The domain key for a specific site, for example `'your_domain_com'`. Pass it together with `view_id`, or by itself for a site with no view configured (see `viewId` in `list_discovery_sites`). Omit both for account level.
`view_id`	`str \| null`	No	The view ID for a specific site, for example `'472'`. Pass it with `domain_key`.
`start_date`	`str \| null`	No	The start of a custom current period, as `YYYYMMDD` or `YYYY-MM-DD`. Pass it with `end_date` to override `days`.
`end_date`	`str \| null`	No	The end of a custom current period. Pass it with `start_date`.
`compare_start_date`	`str \| null`	No	The start of a custom comparison period. Pass it with `compare_end_date` to override the automatic comparison window.
`compare_end_date`	`str \| null`	No	The end of a custom comparison period. Pass it with `compare_start_date`.
`device_type`	`str \| null`	No	Restrict every card to one device: `desktop`, `mobile`, or `tablet`. Omit for all devices combined.

Response parameters

The tool returns a CompassResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict \| null`	The normalized metric cards.
`error`	`str \| null`	Error message if the request failed.

The data object has the following fields:

Field	Type	Description
`current`	`dict`	Each metric's value for the current period, keyed by metric name.
`previous`	`dict`	The same metrics for the comparison period.
`trends`	`dict`	The period-over-period percent change for each metric.
`meta`	`dict`	Report metadata, including the report ID and the date ranges the backend used.

get_discovery_search_performance

Returns the metric cards from the Site search tab, scoped to traffic that came through search. Alongside the four KPIs, you get the engagement metrics that explain them: visits, browse_sessions, bounced_sessions, bounce_rate, product_page_views, atc, atc_rate, and conversions. Every metric carries its comparison-period value and percent change, computed by the backend.

Use it to answer whether search is pulling its weight this month, then drill into the queries behind the numbers with get_discovery_query_performance. Date handling matches the other card tools: a rolling days window by default, or an exact window through start_date and end_date. Set device_type when a mobile-versus-desktop gap is what you're investigating.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to discover sites.
`days`	`int`	No	The rolling window in days, ending on the last available date. Defaults to `30`. Ignored when you pass an explicit window.
`domain_key`	`str \| null`	No	The domain key for a specific site, for example `'your_domain_com'`. Pass it together with `view_id`, or by itself for a site with no view configured (see `viewId` in `list_discovery_sites`). Omit both for account level.
`view_id`	`str \| null`	No	The view ID for a specific site, for example `'472'`. Pass it with `domain_key`.
`start_date`	`str \| null`	No	The start of a custom current period, as `YYYYMMDD` or `YYYY-MM-DD`. Pass it with `end_date` to override `days`.
`end_date`	`str \| null`	No	The end of a custom current period. Pass it with `start_date`.
`compare_start_date`	`str \| null`	No	The start of a custom comparison period. Pass it with `compare_end_date` to override the automatic comparison window.
`compare_end_date`	`str \| null`	No	The end of a custom comparison period. Pass it with `compare_start_date`.
`device_type`	`str \| null`	No	Restrict every card to one device: `desktop`, `mobile`, or `tablet`. Omit for all devices combined.

Response parameters

The tool returns a CompassResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict \| null`	The normalized metric cards.
`error`	`str \| null`	Error message if the request failed.

The data object has the following fields:

Field	Type	Description
`current`	`dict`	Each metric's value for the current period, keyed by metric name.
`previous`	`dict`	The same metrics for the comparison period.
`trends`	`dict`	The period-over-period percent change for each metric.
`meta`	`dict`	Report metadata, including the report ID and the date ranges the backend used.

get_discovery_category_performance

Returns the metric cards from the Category tab, scoped to traffic on category pages. It reports the same metric set as the Site search tab, so you can put the two channels side by side over an identical window: the four KPIs plus visits, browse_sessions, bounced_sessions, bounce_rate, product_page_views, atc, atc_rate, and conversions.

Reach for this tool when a category merchandising change needs a before-and-after read. Pass the exact dates of the change through start_date and end_date, and the equivalent window before it through compare_start_date and compare_end_date. For the per-category breakdown behind these totals, use get_discovery_category_performance_table.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to discover sites.
`days`	`int`	No	The rolling window in days, ending on the last available date. Defaults to `30`. Ignored when you pass an explicit window.
`domain_key`	`str \| null`	No	The domain key for a specific site, for example `'your_domain_com'`. Pass it together with `view_id`, or by itself for a site with no view configured (see `viewId` in `list_discovery_sites`). Omit both for account level.
`view_id`	`str \| null`	No	The view ID for a specific site, for example `'472'`. Pass it with `domain_key`.
`start_date`	`str \| null`	No	The start of a custom current period, as `YYYYMMDD` or `YYYY-MM-DD`. Pass it with `end_date` to override `days`.
`end_date`	`str \| null`	No	The end of a custom current period. Pass it with `start_date`.
`compare_start_date`	`str \| null`	No	The start of a custom comparison period. Pass it with `compare_end_date` to override the automatic comparison window.
`compare_end_date`	`str \| null`	No	The end of a custom comparison period. Pass it with `compare_start_date`.
`device_type`	`str \| null`	No	Restrict every card to one device: `desktop`, `mobile`, or `tablet`. Omit for all devices combined.

Response parameters

The tool returns a CompassResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict \| null`	The normalized metric cards.
`error`	`str \| null`	Error message if the request failed.

The data object has the following fields:

Field	Type	Description
`current`	`dict`	Each metric's value for the current period, keyed by metric name.
`previous`	`dict`	The same metrics for the comparison period.
`trends`	`dict`	The period-over-period percent change for each metric.
`meta`	`dict`	Report metadata, including the report ID and the date ranges the backend used.

get_discovery_products_overview

Returns the metric cards from the Products tab, scoped to product-driven traffic. The metric keys are the four KPIs plus visits, product_page_views, atc, atc_rate, and conversions, each with its comparison-period value and percent change.

This tool covers product engagement in aggregate. For the ranked list of individual products, use get_discovery_product_performance_table, and for a single product's metrics use get_discovery_product_performance. Unlike the other card tools, this one takes no device_type parameter, so the Products cards always cover all devices.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to discover sites.
`days`	`int`	No	The rolling window in days, ending on the last available date. Defaults to `30`. Ignored when you pass an explicit window.
`domain_key`	`str \| null`	No	The domain key for a specific site, for example `'your_domain_com'`. Pass it together with `view_id`, or by itself for a site with no view configured (see `viewId` in `list_discovery_sites`). Omit both for account level.
`view_id`	`str \| null`	No	The view ID for a specific site, for example `'472'`. Pass it with `domain_key`.
`start_date`	`str \| null`	No	The start of a custom current period, as `YYYYMMDD` or `YYYY-MM-DD`. Pass it with `end_date` to override `days`.
`end_date`	`str \| null`	No	The end of a custom current period. Pass it with `start_date`.
`compare_start_date`	`str \| null`	No	The start of a custom comparison period. Pass it with `compare_end_date` to override the automatic comparison window.
`compare_end_date`	`str \| null`	No	The end of a custom comparison period. Pass it with `compare_start_date`.

Response parameters

The tool returns a CompassResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict \| null`	The normalized metric cards.
`error`	`str \| null`	Error message if the request failed.

The data object has the following fields:

Field	Type	Description
`current`	`dict`	Each metric's value for the current period, keyed by metric name.
`previous`	`dict`	The same metrics for the comparison period.
`trends`	`dict`	The period-over-period percent change for each metric.
`meta`	`dict`	Report metadata, including the report ID and the date ranges the backend used.

get_discovery_trend

Returns a daily time series for one metric, with the current period and the comparison period as parallel series you can overlay on a chart. Choose the dashboard tab with tab and the metric with metric. Each series is a list of {cdate, <metric>} records, so the two periods align day for day even when their calendar dates differ.

This tool replaces the retired get_discovery_daily_performance tool. Where that tool returned a fixed pair of sitewide revenue figures, get_discovery_trend plots any metric valid for the tab you pick. Valid tab values are overall, search, category, and products, and each tab accepts the metric keys documented on the matching card tool above. One call plots one metric, so call it again to add a second line to your chart. An unknown tab returns success of False along with the valid tab list.

Request parameters

Name	Type	Required?	Description
`tab`	`str`	No	The tab to plot: `overall`, `search`, `category`, or `products`. Defaults to `overall`.
`metric`	`str`	No	The metric column to plot, for example `visits` or `conversion_rate`. Defaults to `revenue`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to discover sites.
`days`	`int`	No	The rolling window in days, ending on the last available date. Defaults to `30`. Ignored when you pass an explicit window.
`domain_key`	`str \| null`	No	The domain key for a specific site, for example `'your_domain_com'`. Pass it together with `view_id`, or by itself for a site with no view configured (see `viewId` in `list_discovery_sites`). Omit both for account level.
`view_id`	`str \| null`	No	The view ID for a specific site, for example `'472'`. Pass it with `domain_key`.
`start_date`	`str \| null`	No	The start of a custom current period, as `YYYYMMDD` or `YYYY-MM-DD`. Pass it with `end_date` to override `days`.
`end_date`	`str \| null`	No	The end of a custom current period. Pass it with `start_date`.
`compare_start_date`	`str \| null`	No	The start of a custom comparison period. Pass it with `compare_end_date` to override the automatic comparison window.
`compare_end_date`	`str \| null`	No	The end of a custom comparison period. Pass it with `compare_start_date`.

Response parameters

The tool returns a CompassResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict \| null`	The two daily series.
`error`	`str \| null`	Error message if the request failed.

The data object has the following fields:

Field	Type	Description
`metric`	`str`	The metric that was plotted.
`current`	`list[dict]`	The daily series for the current period, each record `{cdate, <metric>}`.
`previous`	`list[dict]`	The daily series for the comparison period, in the same shape.
`meta`	`dict`	Report metadata, including the report ID and the date ranges the backend used.