Path analysis tools
- get_discovery_path_analysis: Get the previous and next paths for one search query or category.
get_discovery_path_analysis
Returns the previous or next paths for one search query or category, as shown on its detail page in the Performance dashboard. Set direction to previous for the events shoppers recorded immediately before the query or category, or to next for the events immediately after it. Rows rank by occurrences, and each carries its previous-period value and percent change.
Choose how far to look with level:
page(default): The adjacent page view. Path types areQUERY,CATEGORY,PRODUCT,PAGE, andHOMEPAGE.session: The adjacent search or category session. Path types areQUERYandCATEGORY.
For a query, pass the query text as value. For a category, pass its cat_id, exactly as returned by get_discovery_performance_table with entity set to category. Matching is exact and case-sensitive for both, and stored values are usually lowercase, so copy the value from a table row rather than retyping it. A sub-ID such as cl1/abc is a separate category and isn't included under cl1. When no paths match and the value's casing or a category display name is the likely cause, the response includes a hint.
Narrow the results with these parameters:
path_typeskeeps only the path types you list, andexclude_path_typesremoves them. Use one or the other.value_containskeeps paths whose value contains a substring, such as a query, category, product ID, or page.url_containskeeps paths whose URL contains a substring, for example/c/.min_occurrencesdrops paths with fewer occurrences in the current period.
Rows are grouped by value and URL, so one page can appear several times when its tracking parameters differ. Add up those rows when you need a single total, or narrow them with url_contains. change_occurrences is N/A for paths with no previous-period occurrences, and those rows sort last when you sort by it. Path data has a shorter history than the other reports, so an older date range can return an empty table. Paths can also be incomplete when page view pixels are missing.
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 item to analyze: query (a search term) or category (by cat_id). |
value | str | int | Yes | The query text or the category's cat_id, exactly as returned by get_discovery_performance_table. Matching is case-sensitive. At the session level, a category display name also works but covers only rows stored under that exact name, so it undercounts. |
direction | str | Yes | previous for the events just before the item, or next for the events just after it. |
level | str | No | page for the adjacent page view, or session for the adjacent search or category session. Defaults to page. |
path_types | list[str] | null | No | Include only these path types, for example ['CATEGORY', 'PRODUCT']. Case-insensitive. Can't be combined with exclude_path_types. |
exclude_path_types | list[str] | null | No | Exclude these path types, for example ['HOMEPAGE']. Case-insensitive. Can't be combined with path_types. |
value_contains | str | null | No | A case-insensitive substring the path's value must contain. |
url_contains | str | null | No | A case-insensitive substring the path's URL must contain, for example '/c/'. |
min_occurrences | int | null | No | Drop paths with fewer occurrences than this in the current period. Must be 1 or higher. |
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: occurrences, prev_occurrences, or change_occurrences. Defaults to occurrences. |
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 path value column. To combine a value filter with the other narrowing parameters, use value_contains instead. |
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 paths. |
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 path. Previous paths hold src_type, src_value, and src_url, and next paths hold tgt_type, tgt_value, and tgt_url. Every row also holds occurrences, prev_occurrences, and change_occurrences. |
total_rows | int | null | The total number of paths 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 total_rows is 0 and the casing of value, or a category display name at the page level, is the likely cause. |
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

