Rule impact tools

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 holds metrics with 36 keys. For each of revenue, aov, conversion_rate, rpv, visits, browse_sessions, bounced_sessions, bounce_rate, product_page_views, atc, atc_rate, and conversions, you get the next-window value, its prev_ value from the previous window, and its change_ percent change. A key can be null. Any warnings are notes, for example that a window is shorter than days.
  • not_measurable: The row has no metrics, and warnings explains 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, and rule_scope each take a string or a list. Several values in a list mean any of them.
  • Metric conditions: metric_filters takes a list of {property, operator, values} conditions, joined with AND, on any of the 36 metric keys or on days_tracked. Values use the response's units, so conversion_rate greater ["2"] means above 2%. Any metric condition hides not_measurable rules, while a days_tracked condition 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

NameTypeRequired?Description
environmentstrNoThe 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_typestr | list[str] | nullNoThe rule types to list: ranking, synonym, or redirect. A list matches any of them. Omit for all three.
applies_tostr | list[str] | nullNoWhat the rules target: query or category. A list matches either. Omit for both.
rule_scopestr | list[str] | nullNoWhere the rule applies: site for one site, or global for the whole account. A list matches either. Omit for both.
metric_filterslist[dict] | nullNoMetric 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.
searchstr | nullNoA case-insensitive substring of the rule name or its values, such as queries or categories.
sortstr | nullNoThe 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_directionstr | nullNoThe sort direction, asc or desc. Defaults to desc.
pageintNoThe page number, 1-based. Defaults to 1.
page_sizeintNoRows per page, from 1 to 100. Defaults to 20.
daysintNoThe 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_namestr | nullNoThe account name. Auto-selected when you have exactly one account. Use list_discovery_accounts to see available accounts.
site_group_idstr | int | nullNoA 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_keystr | nullNoThe 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_idstr | nullNoThe 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:

ParameterTypeDescription
successboolWhether the request succeeded.
datadict | nullThe requested page of rules with their measurements.
errorstr | nullError message if the request failed, including the reason the request was rejected.
environment_usedstr | nullThe 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:

FieldTypeDescription
merchantstrThe account the rules belong to.
snapshot_datestrThe day the rules were read.
daysintThe measurement window used, in days.
first_available_datestrThe first date of performance data the windows can use.
last_available_datestrThe last date of performance data the windows can use.
currencystrThe currency of revenue, AOV, and RPV.
totalintThe total number of rules matching the filters, across all pages.
pageintThe page number returned.
page_sizeintThe number of rows per page.
sortstrThe sort key applied.
sort_directionstrThe sort direction applied.
rowslist[dict]One record per rule. Optional fields are omitted rather than null.
activity_data_availabilitydictHow far the measured data reaches: first_available_date and last_available_date, or error if the lookup failed.
window_notestrA short explanation of the before and after windows.
notestrReturned when no rules matched.
site_scopedictThe 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:

FieldTypeDescription
rule_idstr | intThe rule ID. Pass it with rule_type to get_discovery_rule_impact.
rule_typestrranking, synonym, or redirect.
display_name, rule_namestrThe rule's display name and stored name.
applies_tostrWhether the rule targets queries or categories.
value_type, values, value_countstr, list, intThe queries or categories the rule targets, and how many there are.
rule_scope, domain_key, view_idstrWhere the rule applies: the whole account, or one site.
rule_targetstrThe destination of a redirect rule.
change_kindstrThe kind of change that started tracking.
created_at, last_modified_at, activity_atstrWhen the rule was created, when it was last modified, and when the tracked change happened.
anchor_datestrThe change date the windows are measured around.
days_trackedintThe whole days since the change.
statusstrok when the rule was measured, or not_measurable.
warningslist[str]Why a rule isn't measurable, or notes on a measured rule, such as a partial window.
effective_daysintThe window length actually used.
previous_start_date, previous_end_datestrThe exact previous window.
next_start_date, next_end_datestrThe exact next window.
metricsdictOnly 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

NameTypeRequired?Description
environmentstrNoThe 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_idstr | intYesThe rule ID, from list_discovery_rule_impact or the rule editor.
rule_typestrYesThe rule type: ranking, synonym, or redirect.
daysintNoThe 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_breakdownboolNoSet to true to add the rule's metric cards and one row per target query or category. Defaults to false.
account_namestr | nullNoThe account name. Auto-selected when you have exactly one account. Use list_discovery_accounts to see available accounts.
site_group_idstr | int | nullNoA 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_keystr | nullNoThe 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_idstr | nullNoThe 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:

ParameterTypeDescription
successboolWhether the request succeeded.
datadict | nullThe rule's impact detail.
errorstr | nullError message if the request failed, including the reason the request was rejected.
environment_usedstr | nullThe 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:

FieldTypeDescription
merchantstrThe account the rule belongs to.
snapshot_datestrThe day the rule was read.
ruledictThe rule's fields from its list_discovery_rule_impact row, without the status, warnings, windows, or metrics.
value_typestrThe kind of value the rule targets.
value_countintThe number of targets.
valueslist[dict]The rule's targets, each {value, type}.
drilldowndictThe 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_notestrA short explanation of the before and after windows.
notestrReturned when the rule isn't measurable, with the reason.
breakdowndict | nullReturned when include_breakdown is true. null when nothing could be resolved.
breakdown_notestrReturned when the breakdown was skipped because the drill-down request was incomplete.
site_scopedictThe 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:

FieldTypeDescription
report_idintThe ID of the report behind the target rows.
cardsdictThe 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.
targetsdictrows, 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.


Did this page help you?

© Bloomreach, Inc. All rights reserved.