Product grid insights tools
- get_discovery_product_performance: Get the performance metrics for a single product over the last 30 days.
- search_discovery_product_grid_insights: Preview how products rank for a query and verify your merchandising rules.
get_discovery_product_performance
Returns performance metrics for a single product over the last 30 days: visits, add-to-cart rate, conversion rate, revenue per visit, and total revenue. These metrics come from the tracking pixel on your site, and they feed the ranking algorithm that decides where a product appears in search results.
Use this tool to understand how one product is performing before you adjust its ranking or promotion.
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
product_id | str | Yes | The product to get metrics for. |
account_name | str | null | No | The account name. If you have exactly one account, it's selected for you. Use list_discovery_accounts to see options. |
site_group_id | str | int | null | No | The site group ID or site name. Defaults to -1 (account level). Use list_discovery_sites to find sites. |
domain_key | str | null | No | The domain key for multi-domain accounts, for example 'prod_en'. |
view_id | str | null | No | The view ID for multi-site filtering. |
is_single_domain_account | bool | No | Whether this is a single-domain account. Defaults to false. |
Response parameters
The tool returns a ProductPerformanceResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | ProductPerformanceData | null | The product's performance metrics. |
error | str | null | Error message if the request failed. |
The ProductPerformanceData object has the following fields:
| Field | Type | Description |
|---|---|---|
productId | str | null | The product ID. |
currency | str | null | The currency code, for example 'USD'. |
visits | int | null | Total product page visits in the last 30 days. |
atcRate | float | null | Add-to-cart rate as a fraction, so 0.12 means 12%. |
cvr | float | null | Conversion rate as a fraction, so 0.05 means 5%. |
rpv | float | null | Revenue per visit. |
revenue | float | null | Total revenue generated by this product. |
search_discovery_product_grid_insights
Searches the product grid and returns results as they'd appear on your live site, including product data, ranking scores, facet counts, applied ranking rules, synonyms, and debug info. Use it to preview how products rank for a given query and to verify that your merchandising rules behave as you expect.
The search_by parameter sets the search mode:
search_by | Example query | Behavior |
|---|---|---|
query (default) | 'dress' | Keyword search. |
product_id | '123' | Finds a specific product by its ID. |
category | 'cl10003' | Browses a category by its ID. |
To compare rankings with and without merchandising, call the tool once without disabled_customization_ids to get the baseline grid. Read the active rule IDs from data.debug.experiments[name='customizations_priority'].value.ranking, then call again with some or all of those IDs in disabled_customization_ids. Pass a single ID to isolate one rule, or every ID to see pure algorithmic ranking with no merchandising. Rule IDs are site-specific, so always read them from a prior response.
To compare relevance with and without Loomi Search+, call once with search_mode='hybrid' (semantic and keyword blended) and once with search_mode='standard' (keyword only).
Request parameters
| Name | Type | Required? | Description |
|---|---|---|---|
query | str | Yes | The search term, product ID, or category ID, depending on search_by. |
domain_key | str | Yes | The domain key identifying the catalog, for example 'your_domain_com'. Get it from list_discovery_sites. |
account_name | str | null | No | The account name. If you have exactly one account, it's selected for you. Use list_discovery_accounts to see options. |
site_group_id | str | int | null | No | The site group ID or site name. Defaults to -1 (account level). Use list_discovery_sites to find sites. |
search_by | str | No | The search mode: 'query' (default), 'product_id', or 'category'. |
account_id | int | null | No | A numeric account ID. Defaults to the account resolved from your credentials. |
site_id | int | null | No | A site ID used to resolve the view for multi-site accounts. |
audience_id | int | null | No | An audience ID for personalized results. Use list_discovery_audiences to find audience IDs. |
user_id | str | null | No | The visitor tracking ID (_br_uid_2) for personalized ranking. |
segment | str | null | No | A segment for relevance-by-segment ranking, in the format '<name>:<value>', for example 'customer_country:us'. |
start | int | No | The pagination offset. Defaults to 0. |
rows | int | No | The number of results per page. Defaults to 25. |
groupby | str | null | No | A field to group results by. |
fq | str | null | No | A filter query, for example 'brand:"Acme"'. |
fl | str | null | No | A comma-separated list of fields to return. |
search_mode | str | No | 'hybrid' (default) blends semantic and keyword signals with Loomi Search+. 'standard' applies keyword search only. |
vector_search_temperature | str | No | How strongly semantic signals influence ranking: 'standard' (default) or 'high'. |
disabled_customization_ids | list[str] | null | No | Ranking rule IDs to disable for this query. Read the IDs from a prior response, then pass a subset or all of them. |
simple_debug | bool | No | Include ranking debug info in the response. Defaults to true. Set to false for a leaner response. |
extra_params | dict | null | No | Additional search parameters sent as custom modifiers. Values here override all other defaults. |
Response parameters
The tool returns a ProductGridSearchResponse object with the following parameters:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | any | null | The product grid search results as freeform JSON, with response.docs, facet_counts, and more. |
error | str | null | Error message if the request failed. |
When simple_debug is true, the data payload includes these key fields:
| Field | Description |
|---|---|
response.numFound | Total number of matching products. |
response.docs | Product records with the ranking score, title, pid, and performance signals. |
facet_counts | Facet field counts for filter options. |
debug.rankingAlgorithmName | The ranking algorithm in use. |
debug.synonym.explain.directSynonymsV3 | Synonym expansion chains applied to the query. |
debug.customizations.explain | Active merchandising rule details. |
debug.experiments[name='customizations_priority'].value.ranking | Ordered list of active rule IDs. Use these as disabled_customization_ids. |
debug.disabled_customizations.ids | Rule IDs that were disabled for this call. |