Ranking rules and audiences tools

list_site_search_ranking_rules: List the query-specific site-search ranking rules.
list_ranking_rules_global: List the global ranking rules that apply across site search and category pages.
list_category_ranking_rules: List the query-specific category ranking rules.
get_ranking_rule: Get the full configuration of a single ranking rule.
list_discovery_audiences: List the audience segments used to target rules.
create_ranking_rule: Create a new ranking rule that controls product ordering.
update_ranking_rule: Update an existing ranking rule.
delete_ranking_rule: Permanently delete a ranking rule.
create_ranking_rule_variant: Create an A/B test variant of an existing ranking rule.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Bloomreach dashboard, actions your users or agents take with these tools can have a substantial impact on your live search and category experience. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

list_site_search_ranking_rules

Lists site-search ranking rules as paginated summaries. Ranking rules control how products are ordered in search results for specific queries. For example, a rule can boost certain products to the top when a shopper searches for green shoes. Each rule ties to one or more search queries and can be scheduled, A/B tested, and targeted to an audience.

The summary leaves out the rule's merchandising actions. Use get_ranking_rule for a rule's full configuration. For global ranking rules that apply across both site search and category pages, use list_ranking_rules_global.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`, maximum `100`.
`sort_by`	`str`	No	Field to sort by: `lastModifiedAt`, `identifier`, or `duration`. Defaults to `lastModifiedAt`.
`sort_order`	`str`	No	Sort direction: `ASC` or `DESC`. Defaults to `DESC`.
`q`	`str \| null`	No	Text search to filter by query or username.
`duration`	`str \| null`	No	Comma-separated duration filter: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`audience_ids`	`str \| null`	No	Comma-separated audience IDs to filter by.
`enabled`	`str \| null`	No	Enabled filter: `true` or `false`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The ranking rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, for example `ranking`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`durationTag`	`str \| null`	Duration tag: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`startedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule became active.
`endedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule expires.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was created.
`lastModifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was last modified.
`lastModifiedBy`	`str \| null`	Email or name of the user who last modified the rule.
`queries`	`list[CustomizationQuery]`	The queries this rule applies to.
`isAbTestLive`	`bool`	Whether an A/B test is currently active for this rule.
`audienceName`	`str \| null`	Name of the audience segment this rule targets.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_ranking_rules_global

Lists global ranking rules as paginated summaries. Global ranking rules apply across both site-search and category queries, unlike query-specific rules that affect individual search terms. They suit broad merchandising strategies, such as always boosting in-stock products or demoting clearance items across the whole site.

Each summary includes the name, enabled status, associated queries, A/B test state, and scheduling details. Use get_ranking_rule for a rule's full configuration. For query-specific site-search rules, use list_site_search_ranking_rules.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`, maximum `100`.
`sort_by`	`str`	No	Field to sort by: `lastModifiedAt`, `identifier`, or `duration`. Defaults to `lastModifiedAt`.
`sort_order`	`str`	No	Sort direction: `ASC` or `DESC`. Defaults to `DESC`.
`q`	`str \| null`	No	Text search to filter by identifier or username.
`duration`	`str \| null`	No	Comma-separated duration filter: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`audience_ids`	`str \| null`	No	Comma-separated audience IDs to filter by.
`enabled`	`str \| null`	No	Enabled filter: `true` or `false`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The global ranking rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, for example `ranking`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`durationTag`	`str \| null`	Duration tag: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`startedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule became active.
`endedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule expires.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was created.
`lastModifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was last modified.
`lastModifiedBy`	`str \| null`	Email or name of the user who last modified the rule.
`queries`	`list[CustomizationQuery]`	The queries this rule applies to.
`isAbTestLive`	`bool`	Whether an A/B test is currently active for this rule.
`audienceName`	`str \| null`	Name of the audience segment this rule targets.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_category_ranking_rules

Lists query-specific category ranking rules as paginated summaries. Category ranking rules control how products are ordered on category pages. For example, a rule can boost best-sellers or seasonal items when a shopper browses a specific category. Each rule ties to one or more category queries and can be scheduled, A/B tested, and targeted to an audience.

Use get_ranking_rule for a rule's full configuration. For global rules that apply across all categories and site search, use list_ranking_rules_global.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`, maximum `100`.
`sort_by`	`str`	No	Field to sort by: `lastModifiedAt`, `identifier`, or `duration`. Defaults to `lastModifiedAt`.
`sort_order`	`str`	No	Sort direction: `ASC` or `DESC`. Defaults to `DESC`.
`q`	`str \| null`	No	Text search to filter by category, note, or username.
`duration`	`str \| null`	No	Comma-separated duration filter: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`audience_ids`	`str \| null`	No	Comma-separated audience IDs to filter by.
`enabled`	`str \| null`	No	Enabled filter: `true` or `false`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The category ranking rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, for example `ranking`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`durationTag`	`str \| null`	Duration tag: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`startedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule became active.
`endedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule expires.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was created.
`lastModifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was last modified.
`lastModifiedBy`	`str \| null`	Email or name of the user who last modified the rule.
`queries`	`list[CustomizationQuery]`	The queries this rule applies to.
`isAbTestLive`	`bool`	Whether an A/B test is currently active for this rule.
`audienceName`	`str \| null`	Name of the audience segment this rule targets.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

get_ranking_rule

Fetches the full configuration of a single ranking rule by ID. It works for site-search, category, and global ranking rules. The response returns every merchandising action on the rule: boosted and buried products, locked product slot positions, attribute-level boost and bury adjustments, sliced variant attributes, any ranking algorithm override, and scheduling metadata.

Discover rule IDs with list_site_search_ranking_rules, list_category_ranking_rules, or list_ranking_rules_global, then call this tool to inspect a specific rule's full effect.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the ranking rule to fetch. Discover IDs with `list_site_search_ranking_rules`, `list_category_ranking_rules`, or `list_ranking_rules_global`.
`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 (string). Defaults to `-1` (account level) when omitted. Use `list_discovery_sites` to discover sites.

Response parameters

The tool returns a CustomizationDetailResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The full ranking rule detail as freeform JSON. Includes `id`, `ruleType`, `enabled`, `queries`, `customizationItems` (boosted and buried products, locked slots, attribute boosts), `startedAt`, `endedAt`, and scheduling metadata.
`error`	`str \| null`	Error message if the request failed.

list_discovery_audiences

Lists the audience segments defined in an account. Audiences target ranking rules, redirects, and facets to specific groups of shoppers based on device, location, URL, or referral URL conditions. Use the numeric id from each result as the audience ID when you target a rule to a segment.

Each audience reports how many rules it currently affects and the targeting conditions that define it. Audiences can also draw on Bloomreach segmentations, which enable behavior-based targeting beyond device and location. Audiences are account-level, so this tool takes no site group parameter.

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.

Response parameters

The tool returns an AudiencesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[Audience]`	The audience segments.
`size`	`int \| null`	The total number of audiences returned.
`error`	`str \| null`	Error message if the request failed.

The Audience object has the following fields:

Field	Type	Description
`id`	`int`	The numeric audience ID, used to target a rule to this segment.
`audienceName`	`str`	The human-readable audience name, for example `Mobile Device`.
`user`	`str \| null`	Email of the user who last modified this audience.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the audience was created.
`modifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the audience was last modified.
`rulesAffected`	`int \| null`	The number of ranking rules currently using this audience.
`editable`	`bool \| null`	Whether you can edit this audience.
`dimensionList`	`list[AudienceDimension]`	The targeting conditions that define this audience.
`sitegroup`	`any \| null`	The site group this audience is scoped to, or null for account level.

The AudienceDimension object has the following fields:

Field	Type	Description
`id`	`int \| null`	The dimension ID.
`internalName`	`str \| null`	The internal dimension name, for example `device`, `geo`, `url`, or `ref_url`.
`externalName`	`str \| null`	The human-readable dimension name, for example `Device`, `Location`, `URL`, or `Referral URL`.
`type`	`str \| null`	The dimension type, for example `discovery`.
`dimensionValueList`	`list[any]`	The condition values for this dimension, each with an internal value, an external value, and a match type such as `IS`, `IS NOT`, or `CONTAINS`.

create_ranking_rule

Creates a new ranking rule. Ranking rules control the order of products returned for site-search queries, category pages, or globally, depending on the queryType of each query entry. A rule can boost or bury specific products, freeze product positions, slice variants, override the ranking algorithm, target an audience, and be scheduled with start and end times. Set each query's queryType to sitesearch with a search term, category with a category path, or global, sitesearch_global, or category_global with query='*' to apply the rule across all matching traffic.

When enabled is true, the rule takes effect after an asynchronous sync to the search index (typically seconds to minutes), so it affects live shopper traffic. Only one un-targeted global rule is allowed per queryType; to add another global rule for a queryType that already has one, pass an audience_id. Product boosts and buries have no effect on global rules, queries that contain a colon (:) can't be used, and a buried product is only affected if it already appears in the results for that query. Use list_discovery_audiences to find audience IDs, and confirm the rule synced with list_site_search_ranking_rules, list_category_ranking_rules, or list_ranking_rules_global.

Request parameters

Name	Type	Required?	Description
`queries`	`list[dict]`	Yes	Queries this rule targets. Each entry needs `query` (a search term, category path, or `*` for global rules), `queryType` (`sitesearch`, `category`, `global`, `category_global`, or `sitesearch_global`), and `matchType` (`EXACT_MATCH` or `BROAD`). Use `EXACT_MATCH` for category paths.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level) when omitted.
`name`	`str \| null`	No	Display name for the rule.
`enabled`	`bool`	No	Whether the rule is active immediately after sync. Defaults to `true`.
`audience_id`	`int \| null`	No	Numeric audience segment ID. Required when you create an additional global rule and an un-targeted global rule already exists. Discover IDs with `list_discovery_audiences`.
`boost_product_ids`	`list[str] \| null`	No	Product IDs to boost (surface higher) for this query.
`bury_product_ids`	`list[str] \| null`	No	Product IDs to bury (push lower) for this query.
`freeze_products`	`bool \| null`	No	When `true`, freezes all product positions so the ranking algorithm won't reorder results.
`sliced_attributes`	`list[str] \| null`	No	Attributes to slice variants on, for example `['color', 'size']`.
`ranking_algo_id`	`str \| null`	No	Override the ranking algorithm ID. Omit to use the account default.
`customization_items`	`list[dict] \| null`	No	Advanced: raw items for types not covered by named parameters, such as `attribute_boost_bury` or `product_slots`. Each entry: `{'customizationType': '<type>', 'customizationValue': '<json-string>'}`.
`started_at`	`int \| null`	No	Unix timestamp in milliseconds of when the rule becomes active. Omit for unscheduled.
`ended_at`	`int \| null`	No	Unix timestamp in milliseconds of when the rule expires. Omit for no expiry.

Response parameters

The tool returns a RankingRuleMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The created ranking rule as freeform JSON. Use the returned `id` for later update, delete, or variant operations.
`error`	`str \| null`	Error message if the operation failed.

update_ranking_rule

Updates an existing ranking rule, whether it's a site-search, category, or global rule. Only the fields you provide change; every other field carries forward from the current rule. The tool fetches the current rule, merges your changes on top, then saves the result. Item parameters such as boost_product_ids and freeze_products merge by type, so only the types you specify are replaced while other existing items stay unchanged. Audience targeting is preserved automatically unless you pass a new audience_id, and you can change the query scope by supplying a new queries list.

Changes to an enabled rule affect live search traffic after an asynchronous sync (typically seconds to minutes). Discover the rule ID and confirm its current state with list_site_search_ranking_rules, list_category_ranking_rules, or list_ranking_rules_global before updating.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the ranking rule to update. Discover IDs with `list_site_search_ranking_rules`, `list_category_ranking_rules`, or `list_ranking_rules_global`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level) when omitted.
`name`	`str \| null`	No	New display name. Omit to keep the existing name.
`enabled`	`bool \| null`	No	Enable or disable the rule. Omit to keep the existing state.
`audience_id`	`int \| null`	No	Numeric audience segment ID. Omit to keep the existing audience. Discover IDs with `list_discovery_audiences`.
`queries`	`list[dict] \| null`	No	New query list that replaces the existing one. Each entry: `query`, `queryType`, `matchType`. Omit to keep the existing queries.
`boost_product_ids`	`list[str] \| null`	No	Product IDs to boost. Replaces the existing boosted products. Omit to keep the existing list.
`bury_product_ids`	`list[str] \| null`	No	Product IDs to bury. Replaces the existing buried products. Omit to keep the existing list.
`freeze_products`	`bool \| null`	No	Enable or disable position freezing. Omit to keep the existing setting.
`sliced_attributes`	`list[str] \| null`	No	Attributes to slice variants on. Replaces the existing list. Omit to keep it.
`ranking_algo_id`	`str \| null`	No	Override the ranking algorithm ID. Omit to keep the existing setting.
`customization_items`	`list[dict] \| null`	No	Advanced: raw items merged by `customizationType`, so only the specified types are replaced and others are preserved.
`started_at`	`int \| null`	No	New start timestamp in milliseconds. Omit to keep the existing value.
`ended_at`	`int \| null`	No	New end timestamp in milliseconds. Omit to keep the existing value.

Response parameters

The tool returns a RankingRuleMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The updated ranking rule as freeform JSON.
`error`	`str \| null`	Error message if the operation failed.

delete_ranking_rule

Permanently deletes a ranking rule. This is irreversible — the platform uses a soft delete that filters the rule from all responses with no restore endpoint, so verify the target before you run it. The rule is removed from live search results after an asynchronous sync (typically seconds to minutes), not instantly.

If the rule is currently enabled, it's actively shaping product rankings for shoppers, and deleting it changes search result ordering for all affected queries once the sync completes. Consider disabling it first with update_ranking_rule to preview the impact before removing it. Deletion is blocked when the rule is part of a running A/B experiment, where the API returns a Customization is live error, or when the rule is in the cloning queue; end the experiment or wait for cloning to finish first. Discover IDs with list_site_search_ranking_rules, list_category_ranking_rules, or list_ranking_rules_global.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the ranking rule to delete. Discover IDs with `list_site_search_ranking_rules`, `list_category_ranking_rules`, or `list_ranking_rules_global`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level) when omitted.

Response parameters

The tool returns a DeleteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the delete succeeded.
`error`	`str \| null`	Error message if the delete failed.

create_ranking_rule_variant

Creates a new test variant of an existing ranking rule, equivalent to the Save new test variant button in the Discovery dashboard. Use it to A/B test two different merchandising configurations against each other (Rule A versus Rule B). To test only whether a rule helps against default search behavior, you don't need this tool — omit the customization on the control bucket in create_discovery_experiment instead.

The variant inherits the parent rule's queries, audience, rule type, and site group, so only the merchandising configuration (boost, bury, freeze, and so on) can differ. The variant starts disabled, so enable it with update_ranking_rule before you set up an A/B test. Variants can't be scheduled, so started_at and ended_at aren't supported. The parent rule is variant 1 and this call creates variant 2, up to a maximum of four per group. Inspect the parent rule's full configuration with get_ranking_rule first, then use the returned variant id as the customization when you set up an experiment with create_discovery_experiment.

Request parameters

Name	Type	Required?	Description
`base_rule_id`	`int`	Yes	The ID of the existing ranking rule to create a variant of. Discover IDs with `list_site_search_ranking_rules`, `list_category_ranking_rules`, or `list_ranking_rules_global`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Defaults to `-1` (account level) when omitted.
`name`	`str \| null`	No	Display name for this variant, for example `Boost seasonal products`.
`boost_product_ids`	`list[str] \| null`	No	Product IDs to boost in this variant.
`bury_product_ids`	`list[str] \| null`	No	Product IDs to bury in this variant.
`freeze_products`	`bool \| null`	No	Freeze product positions in this variant.
`sliced_attributes`	`list[str] \| null`	No	Attributes to slice variants on in this variant.
`ranking_algo_id`	`str \| null`	No	Override the ranking algorithm ID for this variant.
`customization_items`	`list[dict] \| null`	No	Advanced: raw customization items. Each entry: `{'customizationType': '<type>', 'customizationValue': '<json-string>'}`.

Response parameters

The tool returns a RankingRuleMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The created variant as freeform JSON. Use the returned `id` as the customization when you set up an experiment with `create_discovery_experiment`.
`error`	`str \| null`	Error message if the operation failed.