Performance analytics tools
- get_discovery_search_performance: Get the KPI tiles for search-driven traffic: revenue, RPV, AOV, and conversion rate.
- get_discovery_category_performance: Get the KPI tiles for category-page traffic: revenue, RPV, AOV, and conversion rate.
- get_discovery_daily_performance: Get sitewide add-to-cart and assisted revenue over a rolling day window.
- get_discovery_top_queries: Get the top search queries ranked by browse sessions and revenue.
- get_discovery_no_revenue_queries: Get search queries that drove sessions but zero revenue.
- get_discovery_top_categories: Get the top categories ranked by browse sessions and revenue.
- get_discovery_lowest_cvr_categories: Get the categories with the lowest conversion rate.
- get_discovery_top_performing_products: Get the top products by revenue, with images and headings.
get_discovery_search_performance
Returns the KPI tiles for search-driven traffic only: revenue, revenue per visit, average order value, and conversion rate. These match the Search tab in the performance dashboard.
The KPIs are pre-calculated server-side rather than derived from raw counts. To compare channels, pair this tool with get_discovery_category_performance for category pages and get_discovery_daily_performance for sitewide totals.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
days | int | No | The rolling window in days, either 7 or 30. Defaults to 30. The window ends yesterday. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | list[any] | Two report payloads: raw metrics and pre-calculated KPIs. |
error | str | null | Error message if the request failed. |
The first payload (data[0]) holds the raw search metrics:
| Field | Description |
|---|---|
visitors | Unique visitors from search. |
visits | Total search visits and sessions. |
revenue | Total search-attributed revenue. |
atc_conversions | Add-to-cart conversions from search. |
The second payload (data[1]) holds the pre-calculated KPIs:
| Field | Description |
|---|---|
snap_atc_rpv | Revenue per visitor. |
snap_atc_aov | Average order value. |
snap_atc_conversion_rate | Conversion rate, as a percentage. |
snap_session_bounce_rate | Session bounce rate, as a percentage. |
get_discovery_category_performance
Returns the KPI tiles for category-page traffic only: revenue, revenue per visit, average order value, and conversion rate. These match the Categories tab in the performance dashboard.
The KPIs are pre-calculated server-side rather than derived from raw counts. To compare channels, pair this tool with get_discovery_search_performance for search traffic and get_discovery_daily_performance for sitewide totals.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
days | int | No | The rolling window in days, either 7 or 30. Defaults to 30. The window ends yesterday. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | list[any] | Two report payloads: raw metrics and pre-calculated KPIs. |
error | str | null | Error message if the request failed. |
The first payload (data[0]) holds the raw category metrics:
| Field | Description |
|---|---|
visitors | Unique visitors from category pages. |
visits | Total category page visits and sessions. |
revenue | Total category-attributed revenue. |
atc_conversions | Add-to-cart conversions from category pages. |
The second payload (data[1]) holds the pre-calculated KPIs:
| Field | Description |
|---|---|
snap_atc_rpv | Revenue per visitor. |
snap_atc_aov | Average order value. |
snap_atc_conversion_rate | Conversion rate, as a percentage. |
snap_session_bounce_rate | Session bounce rate, as a percentage. |
get_discovery_daily_performance
Returns sitewide revenue KPIs over a rolling day window: add-to-cart revenue and assisted revenue (snap_atc_revenue). Unlike the search and category tools, it uses a rolling window rather than a fixed date range.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
days | int | No | The rolling window in days. Defaults to 30, so 30 means the last 30 days. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The report payload as freeform JSON. |
error | str | null | Error message if the request failed. |
get_discovery_top_queries
Returns the top search queries over a date range, ranked by browse session count and revenue. Use it to understand what shoppers search for most. Each query includes its browse session count (browse_session_query) and attributed revenue (snap_atc_revenue).
To contrast high-traffic queries that convert against those that don't, pair this tool with get_discovery_no_revenue_queries.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
start_date | str | Yes | The start date in YYYY-MM-DD format, for example '2026-03-25'. |
end_date | str | Yes | The end date in YYYY-MM-DD format, for example '2026-04-23'. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The report payload as freeform JSON. |
error | str | null | Error message if the request failed. |
get_discovery_no_revenue_queries
Returns search queries that drove sessions but generated zero revenue over a date range. These are searches where shoppers looked but didn't convert, so they're prime candidates for merchandising fixes such as ranking rule adjustments, synonyms, or redirects. Each query includes its browse session count (browse_session_query).
Pair this tool with get_discovery_top_queries to see both ends of the query spectrum.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
start_date | str | Yes | The start date in YYYY-MM-DD format, for example '2026-03-25'. |
end_date | str | Yes | The end date in YYYY-MM-DD format, for example '2026-04-23'. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The report payload as freeform JSON. |
error | str | null | Error message if the request failed. |
get_discovery_top_categories
Returns the top-performing categories over a date range, ranked by browse session count and revenue. Use it to see which category pages drive the most engagement and revenue. Each entry includes the category name and its attributed revenue (snap_atc_revenue).
To see both ends of the performance spectrum, pair this tool with get_discovery_lowest_cvr_categories.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
start_date | str | Yes | The start date in YYYY-MM-DD format, for example '2026-03-25'. |
end_date | str | Yes | The end date in YYYY-MM-DD format, for example '2026-04-23'. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The report payload as freeform JSON. |
error | str | null | Error message if the request failed. |
get_discovery_lowest_cvr_categories
Returns the categories with the lowest conversion rate over a rolling day window, ranked by conversion_after_rate in ascending order. Use it to find category pages that need merchandising attention, such as weak ranking rules, missing products, or thin content. Each entry includes the category name (heading) and its conversion rate (conversion_after_rate).
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
days | int | No | The rolling window in days. Defaults to 30, so 30 means the last 30 days. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The report payload as freeform JSON. |
error | str | null | Error message if the request failed. |
get_discovery_top_performing_products
Returns the top products by revenue over a rolling day window, each with an image URL and heading. Use it to see which products drive the most revenue and to spot candidates for promotional boosting. Each entry includes image_url, product, heading, and revenue.
To boost a top product in search results, use its product ID with the ranking rules tools.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
days | int | No | The rolling window in days. Defaults to 30, so 30 means the last 30 days. |
domain_key | str | null | No | The domain key for a specific site, for example 'your_domain_com'. Omit for account level. |
view_id | str | null | No | The view ID for a specific site, for example '472'. Omit for account level. |
Response parameters
The tool returns a CompassResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The report payload as freeform JSON. |
error | str | null | Error message if the request failed. |