Entity detail tools
- get_discovery_entity_performance: Get the detail-page metric cards for one query, category, product, or brand, with previous-period values.
- get_discovery_entity_products: Get the products behind one query, category, or brand, with product metrics and previous-period values.
- get_discovery_entity_sources: Get the sources of sale for one product, brand, or category.
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
| Name | Type | Required? | Description |
|---|---|---|---|
environment | str | No | The 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. |
entity | str | Yes | The kind of item: query, category (by cat_id), product (by prod_id), or brand. |
value | str | int | Yes | The 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_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 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. |
days | int | No | The 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_key | str | null | No | The 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_id | str | null | No | The 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_date | str | null | No | The 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_date | str | null | No | The end of a custom current period. Pass it with start_date. An end date before the start date is rejected. |
compare_start_date | str | null | No | The 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_date | str | null | No | The end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected. |
device_type | str | null | No | Restrict 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:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | dict | null | The normalized metric cards. |
error | str | null | Error message if the request failed, including the reason the request was rejected. |
environment_used | str | null | The 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:
| Field | Type | Description |
|---|---|---|
current | dict | Each metric's value for the current period, keyed by metric name. |
previous | dict | The same metrics for the comparison period. |
trends | dict | The period-over-period percent change for each metric. |
hint | str | Returned when every metric is zero and the casing of value is the likely cause, or when an unmatched brand needs its exact stored string. |
window | dict | The exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date. |
site_scope | dict | The site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied. |
meta | dict | Report 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
| Name | Type | Required? | Description |
|---|---|---|---|
environment | str | No | The 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. |
entity | str | Yes | The kind of item: query, category (by cat_id), or brand. |
value | str | int | Yes | The 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_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 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. |
days | int | No | The 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_key | str | null | No | The 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_id | str | null | No | The 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_date | str | null | No | The 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_date | str | null | No | The end of a custom current period. Pass it with start_date. An end date before the start date is rejected. |
compare_start_date | str | null | No | The 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_date | str | null | No | The end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected. |
sort | str | null | No | The column to sort by, for example revenue, visits, or conversions. Defaults to revenue. |
sort_direction | str | null | No | The sort direction, asc or desc. Defaults to desc. |
search | str | null | No | A case-insensitive substring that filters the product title or product ID. With a query or category, total_rows is null. |
device_type | str | null | No | Restrict the table to one device: desktop, mobile, tablet, or other (other and unknown devices). Omit for all devices combined. |
page | int | No | The page number, 1-based. Defaults to 1. |
page_size | int | No | Rows 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:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | dict | null | The requested page of table rows. |
error | str | null | Error message if the request failed, including the reason the request was rejected. |
environment_used | str | null | The 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:
| Field | Type | Description |
|---|---|---|
rows | list[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_rows | int | null | The total number of rows matching the filters, across all pages. null when you combine search with a query or category. |
page | int | The page number returned. |
page_size | int | The number of rows per page. |
note | str | Returned when total_rows is null, explaining that you need to page until rows comes back empty. |
hint | str | Returned when nothing matched and the casing of value is the likely cause, or when an unmatched brand needs its exact stored string. |
window | dict | The exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date. |
site_scope | dict | The site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied. |
meta | dict | Report 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,
searchlists the queries that sold it,categorylists the category pages, andotherlists the remaining session types. See sources of product sales. - For a brand,
searchlists the queries andcategorylists the category pages. - For a category,
searchlists every traffic source that led to sales of the category's products. Each row carries atypeofquery,category,homepage, orothers, plus thequery,conversions, andrevenue. Direct landings on a product page aren't included.brandlists 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
| Name | Type | Required? | Description |
|---|---|---|---|
environment | str | No | The 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. |
entity | str | Yes | The kind of item: product (by prod_id), brand, or category (by cat_id). |
value | str | int | Yes | The item, exactly as returned by get_discovery_performance_table: the prod_id, brand, or cat_id. Product and brand matching is case-sensitive. |
source | str | No | The 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_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 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. |
days | int | No | The 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_key | str | null | No | The 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_id | str | null | No | The 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_date | str | null | No | The 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_date | str | null | No | The end of a custom current period. Pass it with start_date. An end date before the start date is rejected. |
compare_start_date | str | null | No | The 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_date | str | null | No | The end of a custom comparison period. Pass it with compare_start_date. An end date before the start date is rejected. |
sort | str | null | No | The column to sort by, for example revenue, visits, or conversions. Defaults to revenue. |
sort_direction | str | null | No | The sort direction, asc or desc. Defaults to desc. |
search | str | null | No | A case-insensitive substring that filters the source column: query, category, session type, or brand. |
device_type | str | null | No | Restrict the table to one device: desktop, mobile, tablet, or other (other and unknown devices). Omit for all devices combined. |
page | int | No | The page number, 1-based. Defaults to 1. |
page_size | int | No | Rows 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:
| Parameter | Type | Description |
|---|---|---|
success | bool | Whether the request succeeded. |
data | dict | null | The requested page of table rows. |
error | str | null | Error message if the request failed, including the reason the request was rejected. |
environment_used | str | null | The 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:
| Field | Type | Description |
|---|---|---|
rows | list[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_rows | int | null | The total number of rows matching the filters, across all pages. |
page | int | The page number returned. |
page_size | int | The number of rows per page. |
hint | str | Returned when nothing matched and the casing of value is the likely cause, or when an unmatched brand needs its exact stored string. |
window | dict | The exact date ranges queried, as ISO dates: start_date, end_date, compare_start_date, and compare_end_date. |
site_scope | dict | The site scope applied: site_group_id, domain_keys, view_ids, and account_level, which is true when no site filter was applied. |
meta | dict | Report metadata, including the report ID and the date ranges the backend used. |
Updated about 4 hours ago

