GrowByData Compass

Published content (articles/pages the AI cited as a source) classified by which brands it mentions: 'domain_only' (mentions your brand, not the competitor's), 'competitor_only' (mentions the competitor, not you -- content/publisher outreach targets), or 'both' (comparison-style content mentioning both -- good targets for improving positioning within existing coverage). Use when: the user wants to know which published articles/pages talk about their brand vs. a competitor's, for content or publisher outreach discovery. Distinct from get_ai_prompt_gap: this tool is keyed on the actual published content, not the search prompt that surfaced it -- use this for "what content covers us" and get_ai_prompt_gap for "what searches are we invisible on." Matches on brand mentions only, not which domain the citation itself is hosted on. Args: domain: The primary publisher domain (your domain). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). competitors: Competitor domains to compare against. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire competitor set) -- at least one of the two is required. domain_groupers: Entity affiliation types from domain_groupers (e.g. ['Competitor']). Use only values returned by initialize_session. platforms: AI platforms to filter by (e.g. ChatGPT, Gemini, Perplexity). Use only values returned by initialize_session. Empty = all; non-empty = filter AND add platform as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. keyword_contains: Substring terms matched against prompt text (case-insensitive, OR logic) to scope which citations are considered. page_limit: Maximum rows to return (default 200). Returns columns: citation_url, citation_domain, platform, search_region, brands_mentioned, distinct_prompts, last_cited_date, mentions_domain, mentions_competitor, overlap_status.

get_citation_content_overlap

Compare Share of Voice across multiple domains side-by-side in one response. Use when: the user wants to compare multiple websites, understand competitive market share, or see how different domains rank against each other. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features aggregated (column omitted); non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated (column omitted); non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows to keywords containing any term. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Compares entire affiliation segments without listing individual domains. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". Use only group names returned by initialize_session. None = aggregate. top_n: Max domains to return per dimension combination (ordered by sov_pct DESC). Default 10. Returns columns: domain, [domain_grouper], [serp_feature], [search_device], [search_region], [label_N], domain_listings, total_listings, sov_pct. Dimension columns are included only when the corresponding filter/group_by is non-empty.

compare_domains_sov

Keywords a competitor (or competitor set) ranks for that `domain` has zero presence in at all — not just "who ranks better," but true absence. Also returns the reverse direction (keywords domain ranks for that the competitor doesn't) unless filtered out via gap_directions. Use when: the user asks what keywords a competitor ranks for that we don't show up for at all, wants a keyword-gap/content-opportunity analysis, or asks "what are we missing vs. [competitor]." Args: domain: The primary publisher domain (your domain). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). competitors: Competitor domains to compare against. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire competitor set) — at least one of the two is required. domain_groupers: Entity affiliation types from domain_groupers (e.g. ['Competitor']). Use only values returned by initialize_session. serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all; non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. gap_directions: 'domain_gap' (competitor ranks, domain doesn't) and/or 'competitor_gap' (domain ranks, competitor(s) don't). Empty = both. page_limit: Maximum rows to return (default 200). Returns columns: search_keyword, serp_feature, search_device, search_region, [entity_affiliation_type], domain_avg_rank, competitor_avg_rank, gap_direction.

get_competitor_keyword_gap

Keywords where two domains both rank, with their average positions compared head-to-head and a winner column. Use when: the user asks about keyword overlap with a competitor, wants head-to-head ranking comparisons, or asks about shared competitive keywords. Args: domain: The primary publisher domain to compare. competitor: The competitor domain to compare against. start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. page_limit: Maximum rows to return (default 200). Returns columns: search_keyword, serp_feature, search_device, search_region, domain_avg_rank, competitor_avg_rank, winner.

get_competitor_overlap

AI search presence for one or more domains across platforms (ChatGPT, Gemini, Perplexity, etc.): how often each is mentioned or cited, and sentiment. Use when: the user asks about AI visibility, brand mentions in AI answers, citations, sentiment, or wants to compare AI presence across multiple brands. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). platforms: AI platforms to filter by (e.g. ChatGPT, Gemini, Perplexity). Empty = all platforms aggregated (column omitted); non-empty = filter AND add platform as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. keyword_contains: Substring terms matched against AI prompt text (case-insensitive, OR logic). Narrows to prompts containing any term, e.g. ["gift"] to scope to gift-related AI searches. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. group_by: Prompt label group name to add as a breakdown dimension, e.g. "Topic". Use only group names returned by initialize_session (prompt labels). None = aggregate across all prompt groups (column omitted). top_n: Max domains to return per dimension combination (ordered by ai_presence_pct DESC). Default 10. Returns columns: domain, [domain_grouper], [platform], [search_region], [label_N], total_searches, searches_brand_mentioned, searches_cited, searches_any_presence, ai_presence_pct, ai_citation_pct, positive_mentions, neutral_mentions, negative_mentions. Platform/region/label columns included only when those filters/group_by are non-empty.

get_domain_ai_presence

Ranking statistics for one or more domains: total appearances, average rank, best rank, and counts of rank-1 / top-3 / top-10 results. Use when: the user asks about average rankings, ranking performance, or how often a domain appears at the top of search results. Pass multiple domains to compare ranking performance side-by-side. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features aggregated (column omitted); non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated (column omitted); non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows to keywords containing any term. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". Use only group names returned by initialize_session. None = aggregate. top_n: Max domains to return per dimension combination (ordered by total_appearances DESC). Default 10. Returns columns: domain, [domain_grouper], [serp_feature], [search_device], [search_region], [label_N], total_appearances, avg_absolute_rank, avg_feature_rank, best_absolute_rank, rank_1_count, top_3_count, top_10_count. Dimension columns are included only when the corresponding filter/group_by is non-empty.

get_domain_rank_summary

Feature presence rate: for each SERP feature type (organic, ads, featured snippet, etc.) what percentage of pages with that feature include each domain. Use when: the user asks which SERP features a domain owns or dominates, wants feature-level presence rates, or compares feature ownership across domains. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated (column omitted); non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows to keywords containing any term. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". Use only group names returned by initialize_session. None = aggregate. top_n: Max domains to return per (serp_feature, ...) combination (ordered by feature_presence_pct DESC). Default 10. Returns columns: domain, serp_feature, [domain_grouper], [search_device], [search_region], [label_N], sessions_domain_present, total_sessions, feature_presence_pct. Device/region/label columns included only when those filters/group_by are non-empty.

get_domain_serp_feature_ownership

Share of Voice (SOV) for one or more domains: what percentage of all SERP listings belong to each, broken down by SERP feature, device, and region. Use when: the user asks about a domain's visibility, market share, or overall SERP presence. Pass multiple domains to compare side-by-side. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features aggregated (column omitted); non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated (column omitted); non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows to keywords containing any term. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category" or "Funnel Stage". Use only group names returned by initialize_session. None = aggregate across all keyword groups (column omitted); non-None = break results out per group value (SOV computed within each group). Make multiple calls for multiple group breakdowns. top_n: Max domains to return per dimension combination (ordered by sov_pct DESC). Default 10. Returns columns: domain, [domain_grouper], [serp_feature], [search_device], [search_region], [label_N], domain_listings, total_listings, sov_pct. Dimension columns are included only when the corresponding filter/group_by is non-empty.

get_domain_sov

All domains competing for a specific keyword in a specific SERP feature, with average rank, best rank, and above-the-fold rate. Use when: the user asks who competes for a keyword in a specific feature (e.g., "who shows up in the shopping carousel for X?"). Args: keyword: The exact search keyword to retrieve feature competition for. serp_feature: The SERP feature type to scope competition to. Use only values returned by initialize_session. start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. page_limit: Maximum rows to return (default 200). Returns columns: item_publisher, search_device, search_region, days_present, avg_rank, best_rank, atf_pct.

get_feature_competition

Load all account context needed for this session. Use when: starting any session, before calling any other tool, and again whenever the user wants to switch account. It returns the only valid values for every enum-like parameter, so no account name, domain name or filter value ever has to be guessed or asked for. IMPORTANT: only call this with account_id_select a SECOND time if the user has explicitly asked to switch accounts in this conversation. Never call it speculatively — e.g. because a brand or domain name was mentioned in passing, or because you're inferring the user might mean a different account. If this session already has an active account and you pass a DIFFERENT account_id_select without confirm_switch=True, the switch is blocked and you'll get a status explaining why — surface that to the user and only retry with confirm_switch=True after they confirm. account_id_select: (optional) Pass the display name of the account to activate (e.g. "Stanley Martin"). Required when your login has access to multiple accounts. Leave empty on first call — if selection is needed, the response will list available account names and prompt you to call again with one selected. confirm_switch: (optional) Pass True only when re-calling with a DIFFERENT account_id_select than the session's current account, after the user has explicitly confirmed they want to switch. Not needed for the first call in a session, or when re-selecting the account that's already active. Returns: account: display name of the active account — always refer to it by this name in responses account_context: (when configured) what this account tracks and why user_context: session context type, use as a soft framing signal only accessible_accounts: display names of the accounts this user can access (JWT mode only) tracked_domains: valid domain values for the `domains` parameter domain_groupers: available grouping labels for this account serp_features: valid values for the `serp_features` parameter on SERP tools search_regions: valid values for `search_regions` ai_platforms: valid values for the `platforms` parameter on AI tools keyword_groupings: available grouping labels for SERP keyword filters prompt_groupings: available grouping labels for AI/prompt tools date_range: valid date ranges per data source quota: (JWT mode only) your daily tool-call limit, remaining calls, and UTC reset time

initialize_session

Granular row-level SERP data for a keyword: every result that appeared each day with domain, rank, position, price, rating, and ATF status. Use when: the user wants deep investigation of a specific keyword's SERP over time, or needs listing-level detail. Args: keyword: The exact search keyword to retrieve granular SERP data for. start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter results. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. page_limit: Maximum rows to return (default 500). page_offset: Rows to skip for pagination (default 0). Returns columns: search_date, domain, content_publisher, serp_feature, search_device, search_region, rank_within_feature, absolute_rank, serp_position, is_above_fold, item_title, item_url_in_search_channel, item_price_text, item_rating, item_review_count.

get_keyword_detail

Day-by-day ranking history for a specific keyword and domain — how its position changed over time. Use when: the user asks about rank trends, how a keyword moved over time, or wants to see a ranking timeline. Args: domain: The publisher domain (item_publisher) to track rank history for. keyword: The exact search keyword to retrieve rank history for. start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter results. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. page_limit: Maximum rows to return (default 500). Returns columns: search_date, serp_feature, rank_within_feature, absolute_rank, is_above_fold, search_device, search_region.

get_keyword_position_history

Full SERP layout for a keyword on a specific date: every result, its rank, domain, title, price, rating, and position. Use when: the user wants to see the complete SERP for a keyword on a given day, or asks "what ranked for X on date Y?". Args: keyword: The exact search keyword to retrieve the SERP snapshot for. search_date: The specific crawl date for the snapshot (YYYY-MM-DD). search_devices: Device types to filter by (e.g. Desktop, Mobile). Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. page_limit: Maximum rows to return (default 200). Returns columns: search_keyword, search_date, search_device, search_region, serp_feature, absolute_rank, rank_within_feature, serp_position, item_publisher, content_publisher, item_title, item_url_in_search_channel, item_price_text, item_rating, item_review_count, is_above_fold.

get_keyword_serp_snapshot

All keywords one or more domains rank for, with average rank, best rank, days present, label group values, and brand/non-brand classification. At least one of serp_features, position_min, position_max, label_filters, brand_or_nonbrand, or keyword_contains must be provided. Use when: the user asks which keywords a domain ranks for, wants to find keywords in a rank range, or filter by category or brand type. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter results. position_min: Minimum absolute rank to include, inclusive. Use with position_max to scope to a rank window (e.g. positions 1–10). position_max: Maximum absolute rank to include, inclusive. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. brand_or_nonbrand: Filter to branded or non-branded keywords. Accepted values: 'Brand Term' or 'Non-Brand Term'. Omit for all. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Use as fallback when a user term does not match any label value, e.g. ["gift", "holiday"]. search_devices: Device types to filter by (e.g. Desktop, Mobile). Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. page_limit: Maximum number of rows to return (1–1000). Default 200. page_offset: Number of rows to skip for pagination. Default 0. Returns columns: search_keyword, serp_feature, search_device, search_region, avg_rank, avg_absolute_rank, best_rank, days_present, last_seen, label group values, brand_or_nonbrand.

get_keywords_by_domain

Keyword + SERP feature combinations where one or more domains had visibility in the baseline period but lost it in the comparison period. Use when: the user asks what rankings were lost, which features dropped out, or wants to identify SERP visibility losses. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). comparison_period_start: Start of the comparison period — the older baseline (YYYY-MM-DD). comparison_period_end: End of the comparison period — the older baseline (YYYY-MM-DD). reporting_period_start: Start of the reporting period — the current window (YYYY-MM-DD). reporting_period_end: End of the reporting period — the current window (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows losses to keywords containing any term, e.g. ["gift"]. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. page_limit: Maximum rows to return (default 200). page_offset: Rows to skip for pagination (default 0). Returns columns: domain, [domain_grouper], search_keyword, serp_feature, [search_device], [search_region], status.

get_lost_features

AI search prompts where one or more brands newly appeared in the comparison period but were not present in the baseline period. Use when: the user asks about new AI search visibility, what queries newly mention the brand, or AI search growth opportunities. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). comparison_period_start: Start of the comparison period — the older baseline (YYYY-MM-DD). comparison_period_end: End of the comparison period — the older baseline (YYYY-MM-DD). reporting_period_start: Start of the reporting period — the current window (YYYY-MM-DD). reporting_period_end: End of the reporting period — the current window (YYYY-MM-DD). platforms: AI platforms to filter by (e.g. ChatGPT, Gemini, Perplexity). Empty = all platforms included. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. keyword_contains: Substring terms matched against prompt text (case-insensitive, OR logic). Narrows to prompts containing any term, e.g. ["gift"]. page_limit: Maximum rows to return (default 200). page_offset: Rows to skip for pagination (default 0). Returns columns: prompt, platform, appearances, avg_mention_rank, avg_citation_rank, positive_count, label group values, change_type.

get_new_ai_appearances

Keywords where one or more domains' rank changed between two periods — gained, lost, or stayed stable. Use when: the user asks about rank changes, what improved or dropped, winners and losers, or period-over-period ranking movement. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). comparison_period_start: Start of the comparison period — the older baseline (YYYY-MM-DD). comparison_period_end: End of the comparison period — the older baseline (YYYY-MM-DD). reporting_period_start: Start of the reporting period — the current window (YYYY-MM-DD). reporting_period_end: End of the reporting period — the current window (YYYY-MM-DD). movement_types: Filter by movement direction. Accepted values: 'gained' (rank improved), 'lost' (rank dropped), 'stable' (within min_rank_change). Empty = all movement types returned. serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. brand_or_nonbrand: Filter to branded or non-branded keywords. Accepted values: 'Brand Term' or 'Non-Brand Term'. Omit for all. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows to rank changes for keywords containing any term, e.g. ["gift"]. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. min_rank_change: Minimum absolute position change to classify as 'gained' or 'lost' (not 'stable'). Default is 3. page_limit: Maximum number of rows to return (1–1000). Default 200. page_offset: Number of rows to skip for pagination. Default 0. Returns columns: item_publisher, search_keyword, [domain_grouper], [serp_feature], [search_device], [search_region], rank_comparison_period, rank_reporting_period, rank_change, movement_type, brand_or_nonbrand.

get_rank_changes

How frequently each SERP feature type appears across all tracked keywords — the landscape of what the SERPs look like. Use when: the user asks about SERP landscape, which features are most common, or wants to understand the overall structure of search results. Args: start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated (column omitted); non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". Use only group names returned by initialize_session. None = aggregate. Returns columns: serp_feature, [search_device], [search_region], [label_N], sessions_with_feature, total_sessions, serp_presence_pct.

get_serp_feature_distribution

SERP feature types (Videos, Featured Snippet, etc.) a competitor or competitor set owns in aggregate across the date range where `domain` has ZERO presence — true absence, not just a low presence rate. Use when: the user asks which SERP features they're completely missing from vs. a competitor, or wants to prioritize feature-type content gaps at a portfolio level (not one specific keyword — see get_feature_competition for that). Args: domain: The primary publisher domain (your domain). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). competitors: Competitor domains to compare against. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire competitor set) — at least one of the two is required. domain_groupers: Entity affiliation types from domain_groupers (e.g. ['Competitor']). Use only values returned by initialize_session. serp_features: Narrow to specific feature types to check. Empty = check all. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. keyword_contains: Substring terms to scope the analysis to a keyword topic (case-insensitive, OR logic), e.g. ['gift']. page_limit: Maximum rows to return (default 200). Returns columns: serp_feature, [search_device], [search_region], [entity_affiliation_type], competitor_sessions_present, total_sessions, competitor_presence_pct.

get_serp_feature_gap

Time-series SERP trend broken down by a single dimension. Returns one row per (period, dimension_value) in long format. The top @top_n dimension values by total appearances over the full date range are pre-selected so output is always bounded. Use when: the user asks how something moved over time on Google SERPs — a trajectory, a trend line, week-over-week or month-over-month change. Use the point-in-time SERP tools instead for a single period's standings. Call this multiple times with different dimensions to build a multi-faceted trend picture (e.g. once for domain, once for serp_feature). Args: start_date: Start of date range (YYYY-MM-DD). end_date: End of date range (YYYY-MM-DD). dimension: Breakdown dimension — one of: 'domain' (publisher domain), 'serp_feature' (SERP feature type), 'search_device' (Desktop/Mobile), 'search_region' (geographic region), 'label_1' (keyword label group 1). top_n: Max number of dimension values to include (1–20, default 10). Values ranked by total appearances over the full date range. time_grain: Period granularity — DAY, WEEK, or MONTH. Omit for auto-selection: ≤30 days→DAY, ≤90 days→WEEK, else MONTH. domains: Filter to these publisher domains (item_publisher). Empty = all. serp_features: Filter to these SERP feature types. Empty = all. search_devices: Filter to these device types. Empty = all. search_regions: Filter to these geographic regions. Empty = all. label_1s: Filter to keywords with these label_1 values. Empty = all. keyword_contains: Filter keywords containing any of these substrings.

get_serp_trends

Share of Voice comparison between two periods for two domains — who gained and who lost market share. Use when: the user asks about SOV changes over time, period comparisons, competitive shifts, or "who grew more visible?" Args: domain: The primary publisher domain. competitor: The competitor domain to compare against. comparison_period_start: Start of the comparison period — the older baseline (YYYY-MM-DD). comparison_period_end: End of the comparison period — the older baseline (YYYY-MM-DD). reporting_period_start: Start of the reporting period — the current window (YYYY-MM-DD). reporting_period_end: End of the reporting period — the current window (YYYY-MM-DD). serp_features: SERP feature types to filter by. Use only values returned by initialize_session. Empty = all features; non-empty = filter AND add serp_feature as a breakdown column. search_devices: Device types to filter by. Empty = all; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions to filter by. Empty = all; non-empty = filter AND add search_region as a breakdown column. Returns columns: item_publisher, search_device, search_region, period (comparison_period / reporting_period), domain_listings, total_listings, sov_pct.

get_sov_shift

Break down one or more domains' Share of Voice by SERP feature type: what fraction of listings come from organic vs ads vs featured snippets, etc. Use when: the user asks how visibility is distributed across feature types, wants paid vs organic breakdown, or compares feature mix across domains. Args: domains: Publisher domains — use only values returned by initialize_session. Mutually usable with domain_groupers (prefer domain_groupers to cover an entire group). start_date: Start of the date range, inclusive (YYYY-MM-DD). end_date: End of the date range, inclusive (YYYY-MM-DD). search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated (column omitted); non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Use only values returned by initialize_session. Empty = all aggregated (column omitted); non-empty = filter AND add search_region as a breakdown column. label_filters: Keyword category filters as {group_name: [values]}, e.g. {"Category": ["Apparel"]}. Use only values returned by initialize_session. keyword_contains: Substring terms matched against keyword text (case-insensitive, OR logic). Narrows to keywords containing any term. domain_groupers: Entity affiliation types from domain_groupers. Use only values returned by initialize_session. Scopes to all domains with these affiliations — no need to list individual domains. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". Use only group names returned by initialize_session. None = aggregate. top_n: Max domains to return per (serp_feature, ...) combination (ordered by sov_within_feature_pct DESC). Default 10. Returns columns: domain, serp_feature, [domain_grouper], [search_device], [search_region], [label_N], domain_listings, domain_total_listings, pct_of_domain_listings, feature_total_listings, sov_within_feature_pct.

get_sov_by_serp_feature

Find all seller name variants in the SERP data that match a brand string. Use when: the user names a brand that is not already in initialize_session().tracked_domains — call this before any SERP query for it. The same brand may appear under slightly different name variants, e.g. 'adidas', 'adidas ny', 'adidas sports'. Without this step, queries may miss some records. Returns a list of matches, each with: seller_name: the publisher string as it appears in the data appearances: total SERP listing rows for this variant keyword_count: number of distinct keywords this variant appears on last_seen: most recent date this variant was seen After receiving the results, present them to the user with appearances counts and ask which variants to treat as the same brand before running any queries. Only pass the user-confirmed variants as the `domains` parameter.

search_brand_sellers

Top advertisers (sellers) in Shopping Ads or Merchant Listings ranked by share of voice, with price, shipping, and rating metrics extracted from item_tags. Use when: the user asks who is winning shopping placements, how sellers compare on price, shipping or rating, or which merchants dominate a product category. Use serp_feature='Shopping Ads' for paid product listings or 'Merchant Listings' for free/organic shopping listings. Valid values are in initialize_session().serp_features. Args: search_devices: Device types (e.g. Desktop, Mobile). Empty = all aggregated; non-empty = filter AND add search_device as a breakdown column. search_regions: Geographic regions. Empty = all aggregated; non-empty = filter AND add search_region as a breakdown column. label_filters: {group_name: [values]} using names from initialize_session().keyword_groupings. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". Use only group names returned by initialize_session. None = aggregate. domain_groupers: [] = ALL advertisers (market view); ['You', 'Competitor'] = tracked only. Returns columns: seller, entity_affiliation_type, [search_device], [search_region], [<group_by>], appearances, sov_pct, avg_rank, avg_price, free_shipping_pct, sale_pct, avg_discount, avg_rating, avg_reviews.

get_shopping_advertiser_summary

Top products (item title + seller) in Shopping Ads or Merchant Listings. Use when: the user asks which individual products or listings are showing up, how a specific item is priced against rivals, or what a competitor is promoting. Use get_shopping_advertiser_summary instead for seller-level rollups. Use serp_feature='Shopping Ads' for paid listings or 'Merchant Listings' for free listings. Valid values are in initialize_session().serp_features. Args: search_devices: Device types. Empty = all aggregated; non-empty = filter AND add breakdown column. search_regions: Regions. Empty = all aggregated; non-empty = filter AND add breakdown column. label_filters: {group_name: [values]} using names from initialize_session().keyword_groupings. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". When set, rank_in_group and rank_overall are scoped within each dimension combination. domain_groupers: [] = ALL advertisers (true market top); ['You', 'Competitor'] = tracked only. Returns columns: item_title, seller, url, entity_affiliation_type, [search_device], [search_region], [<group_by>], appearances, sov_pct, avg_rank, avg_price, free_shipping_pct, sale_pct, avg_discount, avg_rating, avg_reviews, rank_in_group, rank_overall, is_overall_top.

get_shopping_product_summary

Top text ad advertisers ranked by SOV, with keyword coverage, average rank, and above-fold rate. Use when: the user asks who is bidding against them on paid search, how broad a competitor's paid keyword coverage is, or who holds the top ad positions. Use serp_feature from initialize_session().serp_features (e.g. 'Text Ads', 'PPC'). Args: search_devices: Device types. Empty = all aggregated; non-empty = filter AND add breakdown column. search_regions: Regions. Empty = all aggregated; non-empty = filter AND add breakdown column. label_filters: {group_name: [values]} using names from initialize_session().keyword_groupings. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". When set, rank_in_group and rank_overall are scoped within each dimension combination. domain_groupers: [] = ALL advertisers (true market view); ['You', 'Competitor'] = tracked only. Returns columns: advertiser, entity_affiliation_type, [search_device], [search_region], [<group_by>], appearances, keyword_count, sov_pct, avg_rank, above_fold_pct, rank_in_group, rank_overall, is_top_performer.

get_text_ads_advertiser_summary

Text ad copies at title + description level ranked by SOV. Use when: the user asks what messaging, offers or calls to action competitors are running in their ads, or wants the actual ad text behind a paid-search position. Use serp_feature from initialize_session().serp_features. Args: search_devices: Device types. Empty = all aggregated; non-empty = filter AND add breakdown column. search_regions: Regions. Empty = all aggregated; non-empty = filter AND add breakdown column. label_filters: {group_name: [values]} using names from initialize_session().keyword_groupings. group_by: Keyword label group name to add as a breakdown dimension, e.g. "Category". When set, rank_in_group and rank_overall are scoped within each dimension combination. domain_groupers: [] = ALL advertisers (true market leaders); ['You', 'Competitor'] = tracked only. Returns columns: item_title, item_description, advertiser, entity_affiliation_type, [search_device], [search_region], [<group_by>], appearances, keyword_count, sov_pct, avg_rank, above_fold_pct, rank_in_group, rank_overall, is_top_performer.

get_text_ads_copy_analysis

Full list of SERP keywords tracked for this account, with their primary label/category value. Use when: the user asks what keywords are tracked, or as the first step in cross-channel correlation — fetch this list alongside get_ai_answer_keywords(), then use your own reasoning to identify which prompts semantically cover the same topics as which keywords. Then query each dataset independently using the matched inputs. label_filters narrows to a specific topic category — use when you want to correlate only one segment (e.g. just 'Footwear' keywords vs footwear-related prompts) rather than the full keyword universe. Args: label_filters: {group_name: [values]} to narrow to a keyword category, e.g. {"Category": ["Footwear"]}. Empty = return all keywords. Use only values from initialize_session().keyword_groupings. page_limit: Maximum rows to return (1–5000). Default 2000. page_offset: Number of rows to skip for pagination. Default 0. Returns columns: keyword, plus one column per configured keyword group (e.g. "Category", "Funnel Stage").

get_tracked_keywords