Rule impact tools
- list_discovery_rule_impact: List the ranking rules, synonyms, and redirects changed in the last 45 days, with their impact before and after each change.
- get_discovery_rule_impact: Get one rule's impact detail: its targets and, optionally, the metrics for each target query or category.
list_discovery_rule_impact
Returns the Impact measurement tab of the Performance dashboard: every ranking rule, synonym, and redirect changed in the last 45 days, each with its performance before and after its own change date. Use it to answer whether a merchandising change helped, with the same numbers the dashboard shows. Rules running in an A/B test don't appear.
Each rule is measured around the day it changed, so the dashboard's date pickers don't apply and the tool takes no start_date or end_date. days sets the window on either side of the change date. With a change on day T and days of n, the previous window runs from T-n to T-1 and the next window runs from T+1 to T+n, so the change day itself is in neither. Both windows are cut to the available data. Each row returns the exact window dates and effective_days, the window length actually used. days_tracked counts the whole days since the change.
Read status before the numbers:
ok: The row holdsmetricswith 36 keys. For each ofrevenue,aov,conversion_rate,rpv,visits,browse_sessions,bounced_sessions,bounce_rate,product_page_views,atc,atc_rate, andconversions, you get the next-window value, itsprev_value from the previous window, and itschange_percent change. A key can benull. Anywarningsare notes, for example that a window is shorter thandays.not_measurable: The row has nometrics, andwarningsexplains why, for example that the next window hasn't started because the rule changed yesterday.
Rates are already in percent here, so a conversion_rate of 2.98 means 2.98%. Revenue, AOV, and RPV are in the response's currency.
Filter the list two ways, which combine with AND:
- Rule attributes:
rule_type,applies_to, andrule_scopeeach take a string or a list. Several values in a list mean any of them. - Metric conditions:
metric_filterstakes a list of{property, operator, values}conditions, joined with AND, on any of the 36 metric keys or ondays_tracked. Values use the response's units, soconversion_rategreater["2"]means above 2%. Any metric condition hidesnot_measurablerules, while adays_trackedcondition keeps them.
Set search to match a substring in the rule name or its values. Rows sort by the most recent change first by default. You can also sort by a rule field or any metric key, and rows without that metric sort last. Sorting or filtering by a metric measures every matching rule, so it's slower than the default sort.
The response's activity_data_availability shows how far the measured data reaches. When its last_available_date is three or more days old, the list is empty, so report that date rather than concluding that no rules changed. To break one rule down by target, follow up with get_discovery_rule_impact.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
environment | str | No | The target environment: production (default) or staging. The value is case-insensitive, and surrounding whitespace is trimmed. Staging-only accounts always resolve to staging, regardless of this value. |
rule_type | str | list[str] | null | No | The rule types to list: ranking, synonym, or redirect. A list matches any of them. Omit for all three. |
applies_to | str | list[str] | null | No | What the rules target: query or category. A list matches either. Omit for both. |
rule_scope | str | list[str] | null | No | Where the rule applies: site for one site, or global for the whole account. A list matches either. Omit for both. |
metric_filters | list[dict] | null | No | Metric conditions, as a list of {property, operator, values} joined with AND. property is a metric key (<metric>, prev_<metric>, or change_<metric>) or days_tracked. operator is less, less_or_equal, greater, greater_or_equal, equal, not_equal, or between (two values). values are numbers in the response's units, or another metric key. |
search | str | null | No | A case-insensitive substring of the rule name or its values, such as queries or categories. |
sort | str | null | No | The sort key: activity_at (the most recent change), created_at, display_name, rule_type, or any metric key, for example change_revenue. Defaults to activity_at. |
sort_direction | str | null | No | The sort direction, asc or desc. Defaults to desc. |
page | int | No | The page number, 1-based. Defaults to 1. |
page_size | int | No | Rows per page, from 1 to 100. Defaults to 20. |
days | int | No | The measurement window in days on either side of each rule's change date, from 1 to 90. Defaults to 45, the dashboard's setting. |
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 group name. This is the recommended way to scope results to a storefront: results are filtered to the group's member sites. Defaults to -1 (account level). Use list_discovery_sites to discover site groups. |
domain_key | str | null | No | The domain key for one site, for example 'your_domain_com'. Overrides the site group's scope. Valid by itself for a site with no view ID. Use the exact domainKey from list_discovery_sites. |
view_id | str | null | No | The view ID for one site, for example '472'. Pass it with domain_key, and only when list_discovery_sites shows a viewId for that site. A wrong view ID returns the wrong data or none. |
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 requested page of rules with their measurements. |
error | str | null | Error message if the request failed, including the reason the request was rejected. |
environment_used | str | null | The environment actually queried: production or staging. This can differ from the environment you requested, because staging-only accounts always resolve to staging. |
The data object has the following fields:
| Field | Type | Description |
|---|---|---|
merchant | str | The account the rules belong to. |
snapshot_date | str | The day the rules were read. |
days | int | The measurement window used, in days. |
first_available_date | str | The first date of performance data the windows can use. |
last_available_date | str | The last date of performance data the windows can use. |
currency | str | The currency of revenue, AOV, and RPV. |
total | int | The total number of rules matching the filters, across all pages. |
page | int | The page number returned. |
page_size | int | The number of rows per page. |
sort | str | The sort key applied. |
sort_direction | str | The sort direction applied. |
rows | list[dict] | One record per rule. Optional fields are omitted rather than null. |
activity_data_availability | dict | How far the measured data reaches: first_available_date and last_available_date, or error if the lookup failed. |
window_note | str | A short explanation of the before and after windows. |
note | str | Returned when no rules matched. |
site_scope | dict | The site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied. |
Each record in rows has the following fields:
| Field | Type | Description |
|---|---|---|
rule_id | str | int | The rule ID. Pass it with rule_type to get_discovery_rule_impact. |
rule_type | str | ranking, synonym, or redirect. |
display_name, rule_name | str | The rule's display name and stored name. |
applies_to | str | Whether the rule targets queries or categories. |
value_type, values, value_count | str, list, int | The queries or categories the rule targets, and how many there are. |
rule_scope, domain_key, view_id | str | Where the rule applies: the whole account, or one site. |
rule_target | str | The destination of a redirect rule. |
change_kind | str | The kind of change that started tracking. |
created_at, last_modified_at, activity_at | str | When the rule was created, when it was last modified, and when the tracked change happened. |
anchor_date | str | The change date the windows are measured around. |
days_tracked | int | The whole days since the change. |
status | str | ok when the rule was measured, or not_measurable. |
warnings | list[str] | Why a rule isn't measurable, or notes on a measured rule, such as a partial window. |
effective_days | int | The window length actually used. |
previous_start_date, previous_end_date | str | The exact previous window. |
next_start_date, next_end_date | str | The exact next window. |
metrics | dict | Only when status is ok. The 36 metric keys: each metric for the next window, its prev_ value, and its change_ percent change. Rates are in percent. |
get_discovery_rule_impact
Returns one rule's impact measurement detail: the rule with its change date and days tracked, the queries or categories it targets, and the drill-down request the dashboard uses. Take rule_id and rule_type from list_discovery_rule_impact. A rule ID is unique only within its type, so you need both.
Set include_breakdown to true to see which target drove the change. The response then adds the rule's metric cards, which match its row in list_discovery_rule_impact, and one row per target query or category, up to 100, with current and prev_* values. Here, current is the window after the change and previous is the window before it. The cards are raw numbers, while the target rows keep the dashboard's display formatting, such as $12.50, 4.85%, and NA. The breakdown works for redirect rules too.
When the rule can't be drilled into, for example because it changed yesterday and has no next window yet, or because it targets more than 1,000 values, the response carries a note with the reason and breakdown is null. If the rule isn't tracked, because it isn't active, runs in an A/B test, or changed more than 45 days ago, or the measured data is three or more days old, the request fails with the reason in error.
A site rule is measured on its own site. Pass domain_key and view_id only to pick one site's row of a rule that applies to several sites.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
environment | str | No | The target environment: production (default) or staging. The value is case-insensitive, and surrounding whitespace is trimmed. Staging-only accounts always resolve to staging, regardless of this value. |
rule_id | str | int | Yes | The rule ID, from list_discovery_rule_impact or the rule editor. |
rule_type | str | Yes | The rule type: ranking, synonym, or redirect. |
days | int | No | The measurement window in days on either side of the rule's change date, from 1 to 90. Defaults to 45, the dashboard's setting. |
include_breakdown | bool | No | Set to true to add the rule's metric cards and one row per target query or category. Defaults to false. |
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 group name. This is the recommended way to scope results to a storefront: results are filtered to the group's member sites. Defaults to -1 (account level). Use list_discovery_sites to discover site groups. |
domain_key | str | null | No | The domain key for one site, for example 'your_domain_com'. Overrides the site group's scope. Valid by itself for a site with no view ID. Use the exact domainKey from list_discovery_sites. |
view_id | str | null | No | The view ID for one site, for example '472'. Pass it with domain_key, and only when list_discovery_sites shows a viewId for that site. A wrong view ID returns the wrong data or none. |
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 rule's impact detail. |
error | str | null | Error message if the request failed, including the reason the request was rejected. |
environment_used | str | null | The environment actually queried: production or staging. This can differ from the environment you requested, because staging-only accounts always resolve to staging. |
The data object has the following fields:
| Field | Type | Description |
|---|---|---|
merchant | str | The account the rule belongs to. |
snapshot_date | str | The day the rule was read. |
rule | dict | The rule's fields from its list_discovery_rule_impact row, without the status, warnings, windows, or metrics. |
value_type | str | The kind of value the rule targets. |
value_count | int | The number of targets. |
values | list[dict] | The rule's targets, each {value, type}. |
drilldown | dict | The request the dashboard uses to drill into the rule's targets, or a note with a warning code when the rule can't be drilled into. |
window_note | str | A short explanation of the before and after windows. |
note | str | Returned when the rule isn't measurable, with the reason. |
breakdown | dict | null | Returned when include_breakdown is true. null when nothing could be resolved. |
breakdown_note | str | Returned when the breakdown was skipped because the drill-down request was incomplete. |
site_scope | dict | The site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied. |
The breakdown object has the following fields:
| Field | Type | Description |
|---|---|---|
report_id | int | The ID of the report behind the target rows. |
cards | dict | The rule's own row from list_discovery_rule_impact: status, warnings, effective_days, the four window dates, days_tracked, and the 36 raw metrics. Holds error instead when the row couldn't be matched, with sites when the rule has one row per site. |
targets | dict | rows, one record per target query or category with current and prev_* metrics, up to 100, plus meta and window. Holds error instead if the targets couldn't be retrieved. |
Updated about 4 hours ago

