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.

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`.