Media rules and assets tools

list_site_search_media_rules: List the media rules that inject sponsored content into site search results.
list_category_media_rules: List the media rules that inject sponsored content on category pages.
list_global_media_rules: List the site-wide media rules that apply across all search and category pages.
get_discovery_media_rule: Get the full configuration of a single media rule by ID.
list_discovery_assets: List the reusable media assets, such as banners, weblayers, and Clarity elements.
get_discovery_asset: Get a single asset's full details, including its content payload.
get_discovery_weblayer_customizations: List the media rules that reference a weblayer asset.
get_discovery_multi_slot_customizations: List the media rules that use multi-slot content grid assets.

list_site_search_media_rules

Lists the site-search media rules (campaigns) in your account. Media rules inject sponsored content, banners, and promotional placements into search results for specific queries. Unlike ranking rules, which reorder organic products, media rules add paid or promoted content to the results page.

Each rule targets one or more search queries and can be scheduled, A/B tested, and aimed at an audience. The response returns paginated rule summaries with enabled status, scheduling, and associated queries. Use the duration filter to find rules that are about to expire or have already expired, and get_discovery_media_rule for a rule's full configuration.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	Page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`.
`sort_by`	`str`	No	Field to sort by. 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	Duration filter, comma-separated: `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 media rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The media rule's unique ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type. Always `campaign` for media rules.
`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.

list_category_media_rules

Lists the category media rules (campaigns) in your account. These media rules inject sponsored content, banners, and promotional placements onto category pages. Unlike ranking rules, which reorder organic products, media rules add paid or promoted content to the category browsing experience.

Each rule targets one or more category queries and can be scheduled, A/B tested, and aimed at an audience. The response returns paginated rule summaries with enabled status, scheduling, and associated queries. Use get_discovery_media_rule for a rule's full configuration.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	Page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`.
`sort_by`	`str`	No	Field to sort by. 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	Duration filter, comma-separated: `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 media rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object is described under list_site_search_media_rules.

list_global_media_rules

Lists the global media rules (campaigns) in your account. Global media rules control sponsored content and promotional placements that appear across all site search and category pages, regardless of the specific query or category. Unlike query-scoped or category-scoped rules, global rules apply universally, which makes them a fit for site-wide promotions and seasonal campaigns.

The response returns paginated rule summaries with enabled status, scheduling, and associated queries. Use get_discovery_media_rule for a rule's full configuration.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	Page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`.
`sort_by`	`str`	No	Field to sort by. 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	Duration filter, comma-separated: `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 media rule summaries.
`error`	`str \| null`	Error message if the request failed.

The CustomizationSummary object is described under list_site_search_media_rules.

get_discovery_media_rule

Returns the full configuration for a single media rule (campaign customization) by ID. The response includes the associated queries with their match types, scheduling, the campaign items (banners and content grid placements with slot positions and dimensions), audience targeting, A/B test state, and sync status.

Use list_site_search_media_rules, list_category_media_rules, or list_global_media_rules to find customization IDs.

Request parameters

Name	Type	Required?	Description
`customization_id`	`int`	Yes	The customization ID from a media rules list tool.

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 media rule configuration, as freeform JSON.
`error`	`str \| null`	Error message if the request failed.

The data object contains the following key fields:

Field	Type	Description
`id`	`int`	The media rule's ID.
`name`	`str`	The rule name.
`ruleType`	`str`	Always `campaign` for media rules.
`enabled`	`bool`	Whether the rule is active.
`queries`	`list`	The queries this rule applies to. Each has a `query`, a `queryType`, and a `matchType` of `exact_match` or `broad_match`.
`customizationItems`	`object`	The media placements. Contains `campaign` (a top banner spanning the grid width) and `content_in_grid` (in-grid placements between products, with banner IDs, slot positions, and dimensions).
`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.
`audience`	`object`	Audience targeting, with an `id` and an `audienceName`.
`syncStatus`	`str`	Sync status: `SUCCESS`, `QUEUED`, or `FAILED`.
`sharedId`	`int`	The ID of the shared asset this rule references.
`influence`	`str`	The rule's scope, for example `Global` or `Query`.

list_discovery_assets

Lists the reusable media assets in your account. Assets are shared content items — banners, weblayers, and Clarity elements — that media rules reference. The response returns paginated asset summaries, which you can filter by data type or name.

To fetch a single asset's full content payload, pass its ID to get_discovery_asset. If you have access to more than one account, set account_name.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Specify one if you have access to multiple accounts. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to account level (`-1`). Use `list_discovery_sites` to see available sites.
`page`	`int`	No	Page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `10`.
`sort_by`	`str`	No	Field to sort by: `modifiedAt`, `createdAt`, `name`, or `dataType`. Defaults to `modifiedAt`.
`sort_order`	`str`	No	Sort direction: `ASC` or `DESC`. Defaults to `DESC`.
`data_types`	`str \| null`	No	Comma-separated data types to filter by: `banners`, `weblayer`, or `clarity`.
`q`	`str \| null`	No	Search term to filter assets by name.

Response parameters

The tool returns an AssetsResponse object with the following parameters:

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

The AssetSummary object has the following fields:

Field	Type	Description
`sharedDataId`	`int \| null`	The asset's ID. Pass this to `get_discovery_asset`.
`name`	`str \| null`	The asset name.
`dataType`	`str \| null`	The data type: `banners`, `weblayer`, or `clarity`.
`user`	`str \| null`	The user who last modified the asset.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the asset was created.
`modifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the asset was last modified.
`merchantName`	`str \| null`	The merchant name.
`domainKey`	`str \| null`	The domain key.
`deleted`	`bool \| null`	Whether the asset has been deleted.
`sitegroupId`	`int \| null`	The site group ID.
`sharedData`	`str \| null`	The asset content, as a JSON string. Populated when you fetch a single asset with `get_discovery_asset`.

get_discovery_asset

Returns the full details of a single asset by ID, including its content payload. The sharedData field holds the asset's content as a JSON string, such as the banner markup, weblayer definition, or Clarity configuration.

Use list_discovery_assets to find asset IDs.

Request parameters

Name	Type	Required?	Description
`shared_data_id`	`int`	Yes	The asset ID returned by `list_discovery_assets`.
`account_name`	`str \| null`	No	The account name. Specify one if you have access to multiple accounts. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to account level (`-1`). Use `list_discovery_sites` to see available sites.

Response parameters

The tool returns an AssetResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`AssetSummary \| null`	The asset details, including the content payload.
`error`	`str \| null`	Error message if the request failed.

The AssetSummary object is described under list_discovery_assets. When you fetch a single asset, the sharedData field holds the full content payload.

get_discovery_weblayer_customizations

Lists the media rules that reference a specific weblayer asset. Use this to find which campaigns depend on a weblayer before you change or retire it. The response returns each referencing customization along with the queries it applies to.

Use list_discovery_assets to find weblayer asset IDs.

Request parameters

Name	Type	Required?	Description
`weblayer_id`	`str`	Yes	The weblayer ID to look up customizations for.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to account level (`-1`). Use `list_discovery_sites` to see available sites.

Response parameters

The tool returns an AssetCustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[AssetCustomization]`	The media rules that reference this weblayer asset.
`error`	`str \| null`	Error message if the request failed.

The AssetCustomization object has the following fields:

Field	Type	Description
`id`	`int \| null`	The customization ID.
`name`	`str \| null`	The customization name.
`queries`	`list[AssetCustomizationQuery]`	The queries this customization applies to.

The AssetCustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query ID.
`query`	`str \| null`	The query text.
`queryType`	`str \| null`	The query type, for example `sitesearch` or `category`.
`matchType`	`str \| null`	The match type: `exact` or `broad`.

get_discovery_multi_slot_customizations

Lists the media rules that use multi-slot content grid assets. A multi-slot asset places several promotional items in a single content grid slot. The response returns each customization along with the queries it applies to.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to account level (`-1`). Use `list_discovery_sites` to see available sites.

Response parameters

The tool returns an AssetCustomizationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[AssetCustomization]`	The media rules that reference multi-slot assets.
`error`	`str \| null`	Error message if the request failed.

The AssetCustomization object is described under get_discovery_weblayer_customizations.