Entity detail tools

get_discovery_entity_performance

Returns the metric cards from one item's detail page in the Performance dashboard: the page that opens when you click a row in the queries, categories, products, or brands table. Choose the item with entity and value.

Queries and categories return visits, browse_sessions, bounced_sessions, bounce_rate, product_page_views, atc, atc_rate, conversions, revenue, rpv, conversion_rate, and aov. Products and brands return the same set without the session and bounce metrics. Every metric arrives with its comparison-period value and the percent change between them. For the item's daily series, call get_discovery_trend with the same entity and value.

Pass value exactly as it appears in a get_discovery_performance_table row: the query text, the category's cat_id, the product's prod_id, or the brand. To find a product, category, or brand by title, use the table tool's search parameter first. Matching is exact and case-sensitive for queries, categories, and products. Brands keep their stored mixed case, for example Brother, so neither BROTHER nor brother matches. Categories also accept the exact stored display name, but the cat_id is more reliable.

An unknown value returns all-zero metrics rather than an error. When that happens for a mixed-case query, category, or product value, or for any brand, the response includes a hint. For a brand, the hint points you to get_discovery_performance_table with entity set to brand and a search value, so you can copy the exact stored string.

To scope results to one storefront, pass site_group_id. Results then cover only that group's member sites, and site_scope in the response shows which sites were applied.

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.
entitystrYesThe kind of item: query, category (by cat_id), product (by prod_id), or brand.
valuestr | intYesThe item, exactly as returned by get_discovery_performance_table: the query text, cat_id, prod_id, or brand. Matching is case-sensitive, and brands keep their stored mixed case.
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.
daysintNoThe rolling window in days, from 1 to 730, ending on the last available date. Defaults to 30. Ignored when you pass start_date and end_date.
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.
start_datestr | nullNoThe start of a custom current period, as YYYYMMDD or YYYY-MM-DD. Pass it with end_date to override days. The period can span up to 730 days.
end_datestr | nullNoThe end of a custom current period. Pass it with start_date. An end date before the start date is rejected.
compare_start_datestr | nullNoThe start of a custom comparison period. Pass it with compare_end_date to override the automatic comparison window. The period can span up to 730 days.
compare_end_datestr | nullNoThe end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected.
device_typestr | nullNoRestrict every card to one device: desktop, mobile, tablet, or other (other and unknown devices). Omit for all devices combined.

Response parameters

The tool returns a CompassResponse object with the following parameters:

ParameterTypeDescription
successboolWhether the request succeeded.
datadict | nullThe normalized metric cards.
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
currentdictEach metric's value for the current period, keyed by metric name.
previousdictThe same metrics for the comparison period.
trendsdictThe period-over-period percent change for each metric.
hintstrReturned when every metric is zero and the casing of value is the likely cause, or when an unmatched brand needs its exact stored string.
windowdictThe exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date.
site_scopedictThe site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied.
metadictReport metadata, including the report ID and the date ranges the backend used.

get_discovery_entity_products

Returns the products table from one item's detail page: the products shoppers engaged with after a search query, on a category's pages, or within a brand. Each row carries the product ID, title, image URL, and product URL, plus visits, product_page_views, atc, atc_rate, conversions, revenue, rpv, conversion_rate, and aov, each paired with its prev_* previous-period value. Brand rows also carry the brand.

Rows sort by revenue descending by default. Set sort and sort_direction to rank them yourself, and search to match a substring in the product title or product ID. When you combine search with a query or a category, the total isn't available, so total_rows is null and the response includes a note. In that case, page until rows comes back empty.

Pass value the same way as for get_discovery_entity_performance. This tool doesn't take entity of product; for a single product's breakdown, use get_discovery_entity_sources. When nothing matches a mixed-case query or category value, or an unmatched brand, and you didn't set search, the response includes a hint.

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.
entitystrYesThe kind of item: query, category (by cat_id), or brand.
valuestr | intYesThe item, exactly as returned by get_discovery_performance_table: the query text, cat_id, or brand. Matching is case-sensitive, and brands keep their stored mixed case.
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.
daysintNoThe rolling window in days, from 1 to 730, ending on the last available date. Defaults to 30. Ignored when you pass start_date and end_date.
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.
start_datestr | nullNoThe start of a custom current period, as YYYYMMDD or YYYY-MM-DD. Pass it with end_date to override days. The period can span up to 730 days.
end_datestr | nullNoThe end of a custom current period. Pass it with start_date. An end date before the start date is rejected.
compare_start_datestr | nullNoThe start of a custom comparison period. Pass it with compare_end_date to override the automatic comparison window. The period can span up to 730 days.
compare_end_datestr | nullNoThe end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected.
sortstr | nullNoThe column to sort by, for example revenue, visits, or conversions. Defaults to revenue.
sort_directionstr | nullNoThe sort direction, asc or desc. Defaults to desc.
searchstr | nullNoA case-insensitive substring that filters the product title or product ID. With a query or category, total_rows is null.
device_typestr | nullNoRestrict the table to one device: desktop, mobile, tablet, or other (other and unknown devices). Omit for all devices combined.
pageintNoThe page number, 1-based. Defaults to 1.
page_sizeintNoRows per page, from 1 to 100. Defaults to 20. Use page to fetch more rows.

Response parameters

The tool returns a CompassResponse object with the following parameters:

ParameterTypeDescription
successboolWhether the request succeeded.
datadict | nullThe requested page of table rows.
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
rowslist[dict]One record per product, holding prod_id, product_title, image_url, and product_url, plus every metric and its prev_* value. Brand rows also hold brand.
total_rowsint | nullThe total number of rows matching the filters, across all pages. null when you combine search with a query or category.
pageintThe page number returned.
page_sizeintThe number of rows per page.
notestrReturned when total_rows is null, explaining that you need to page until rows comes back empty.
hintstrReturned when nothing matched and the casing of value is the likely cause, or when an unmatched brand needs its exact stored string.
windowdictThe exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date.
site_scopedictThe site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied.
metadictReport metadata, including the report ID and the date ranges the backend used.

get_discovery_entity_sources

Returns the sources of sale table from one item's detail page: where a product, a brand, or a category's products sell. Choose the breakdown with source, which defaults to search:

  • For a product, search lists the queries that sold it, category lists the category pages, and other lists the remaining session types. See sources of product sales.
  • For a brand, search lists the queries and category lists the category pages.
  • For a category, search lists every traffic source that led to sales of the category's products. Each row carries a type of query, category, homepage, or others, plus the query, conversions, and revenue. Direct landings on a product page aren't included. brand lists the brands sold on the category's pages. See where category products sell.

Product and brand rows carry the source plus visits, product_page_views, atc, conversions, and revenue, each paired with its prev_* previous-period value. Rows sort by revenue descending by default, and search matches a substring in the source column.

Pass value the same way as for get_discovery_entity_performance. Product and brand values are case-sensitive, while category reports match the cat_id regardless of case. When nothing matches a mixed-case product value or a brand, the response includes a hint. An entity and source pair that doesn't fit returns success of False with the valid sources for that entity.

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.
entitystrYesThe kind of item: product (by prod_id), brand, or category (by cat_id).
valuestr | intYesThe item, exactly as returned by get_discovery_performance_table: the prod_id, brand, or cat_id. Product and brand matching is case-sensitive.
sourcestrNoThe breakdown to return: search, category, or other for a product; search or category for a brand; search or brand for a category. Defaults to search.
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.
daysintNoThe rolling window in days, from 1 to 730, ending on the last available date. Defaults to 30. Ignored when you pass start_date and end_date.
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.
start_datestr | nullNoThe start of a custom current period, as YYYYMMDD or YYYY-MM-DD. Pass it with end_date to override days. The period can span up to 730 days.
end_datestr | nullNoThe end of a custom current period. Pass it with start_date. An end date before the start date is rejected.
compare_start_datestr | nullNoThe start of a custom comparison period. Pass it with compare_end_date to override the automatic comparison window. The period can span up to 730 days.
compare_end_datestr | nullNoThe end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected.
sortstr | nullNoThe column to sort by, for example revenue, visits, or conversions. Defaults to revenue.
sort_directionstr | nullNoThe sort direction, asc or desc. Defaults to desc.
searchstr | nullNoA case-insensitive substring that filters the source column: query, category, session type, or brand.
device_typestr | nullNoRestrict the table to one device: desktop, mobile, tablet, or other (other and unknown devices). Omit for all devices combined.
pageintNoThe page number, 1-based. Defaults to 1.
page_sizeintNoRows per page, from 1 to 100. Defaults to 20. Use page to fetch more rows.

Response parameters

The tool returns a CompassResponse object with the following parameters:

ParameterTypeDescription
successboolWhether the request succeeded.
datadict | nullThe requested page of table rows.
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
rowslist[dict]One record per source. Product and brand rows hold source plus every metric and its prev_* value. Category rows hold type, query, conversions, and revenue for search, or brand and its metrics for brand.
total_rowsint | nullThe total number of rows matching the filters, across all pages.
pageintThe page number returned.
page_sizeintThe number of rows per page.
hintstrReturned when nothing matched and the casing of value is the likely cause, or when an unmatched brand needs its exact stored string.
windowdictThe exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date.
site_scopedictThe site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied.
metadictReport metadata, including the report ID and the date ranges the backend used.


Did this page help you?

© Bloomreach, Inc. All rights reserved.