Skip to content

Examples

These examples show realistic prompts, the kind of tools the agent may call, and representative output. The exact tools and sequence will vary between runs - agents choose their own approach based on the question. All data shown is illustrative.

1. Market Share Overview

What you ask:

Show me my market share in the UK for the last 30 days. Who are my top competitors and how do we compare?

Tools the agent may use:

  1. list_accessible_accounts(location="United Kingdom") to find the right account
  2. get_market_share(report_type="summary") for the high-level overview
  3. get_market_share(report_type="detail", page_size=10) for competitor-level detail

What you get:

Here's your UK market share for the last 30 days:

Your Position:

  • Share of Clicks: 18.5% (3rd in market)
  • Share of Spend: 22.1%
  • Average Position: 2.3
  • Average CPC: $1.45

Market Overview: 87 active competitors. Market leader: competitor-a.com at 24.3% share of clicks.

Top 5 Competitors:

Competitor Share of Clicks Share of Spend Avg Position Search Terms
competitor-a.com 24.3% 28.1% 1.8 2,450
competitor-b.co.uk 19.2% 17.5% 2.1 1,890
yourdomain.com 18.5% 22.1% 2.3 2,100
competitor-c.com 12.7% 10.3% 2.8 1,540
competitor-d.co.uk 8.4% 9.2% 3.1 980

You're spending more relative to your click share (22.1% spend vs 18.5% clicks), suggesting a higher CPC than average. competitor-b.co.uk achieves a similar share with lower relative spend - it could be worth analyzing their strategy.

2. Competitor Deep Dive

What you ask:

I want to understand what competitor-a.com is doing differently. Show me our search term overlap, their top ads, and how their share has trended over the last 3 months.

Tools the agent may use:

  1. get_competitor_overlap(competitor=["competitor-a.com"]) to analyze shared search terms
  2. get_ads(competitor=["competitor-a.com"], ad_format="text") to see their ad copies
  3. get_market_trends(competitor=["competitor-a.com"]) for their share over time

What you get:

Here's the deep dive on competitor-a.com over the last 3 months:

Search Term Overlap:

  • Your search terms: 2,100
  • Their search terms: 2,450
  • Shared terms: 1,680 (overlap ratio: 80%)
  • Terms only they bid on: 770
  • Estimated clicks on shared terms: 45,200

They cover 80% of your terms plus 770 you're not present on - a significant gap.

Their Top Ads (most frequent):

  1. "Best Deals on [Category] | Free Shipping | competitor-a.com" - 340 search terms, avg position 1.8
  2. "Official [Category] Store | Price Match Guarantee" - 280 search terms, avg position 2.1
  3. "Save Up to 40% | [Category] Sale Now On" - 195 search terms, avg position 1.5

They lead with price/value messaging and frequently hold positions 1-2.

Share of Clicks Trend (weekly):

Period competitor-a.com You
January 22.1% 19.8%
February 23.5% 18.9%
March 24.3% 18.5%

Their share has grown +2.2pp over 3 months while yours declined -1.3pp. The gap is widening.

3. Brand Protection with SERP Tracker

SERP Tracker (formerly Infringement Tracker) returns rule matches - ads on the SERP that triggered a configured rule. A match is not a legal infringement. For trademark-specific cases use get_auto_takedown; for Google's enforcement outcomes on those cases use get_trademark_takedowns.

What you ask:

Check if any competitors are using our brand name in their ads. Show me SERP Tracker matches from the past two weeks.

Tools the agent may use:

  1. get_serp_tracker(report_type="summary") for an overview
  2. get_serp_tracker(report_type="matches", page_size=20) for specific matches

What you get:

SERP Tracker Summary (last 2 weeks):

  • Total rule matches: 23
  • Unique competitors matching rules: 5
  • Unique search terms affected: 12
  • Desktop: 15 matches | Mobile: 8 matches

Top Matching Competitors:

Competitor Matches
shadydealer.com 9
bargain-outlet.co.uk 6
deals-compare.com 4
reseller-xyz.com 3
affiliate-site.net 1

Recent Matches (sample):

  1. shadydealer.com on "yourbrand shoes sale" (Apr 11, desktop)

    • Ad: "Official YourBrand Shoes - 50% Off Today Only"
    • Display URL: shadydealer.com/yourbrand

  2. bargain-outlet.co.uk on "buy yourbrand online" (Apr 10, mobile)

    • Ad: "YourBrand Products - Lowest Prices Guaranteed"
    • Display URL: bargain-outlet.co.uk

shadydealer.com is the most active match source with 9 matches, specifically targeting brand + product terms with misleading "Official" claims. If you want to pursue trademark enforcement against them, check get_auto_takedown for trademark-specific detections that Google will action.

4. Search Term Opportunities

What you ask:

Find search term opportunities - terms my competitors are bidding on that I'm missing. Focus on high-traffic terms.

Tools the agent may use:

  1. get_search_terms(report_type="opportunities_summary") for an overview
  2. get_search_terms(report_type="opportunities", order_by="estimated_clicks", page_size=20) for the top gaps

What you get:

Search Term Opportunities Overview:

There are terms your competitors actively bid on where you have no presence. Here are the highest-traffic gaps:

Search Term Est. Clicks Competitors Top Competitor Avg Position
best [category] deals 2026 1,240 8 competitor-a.com 1.5
[category] comparison tool 890 6 competitor-b.co.uk 2.0
cheap [category] uk delivery 720 5 competitor-c.com 1.8
[category] reviews and prices 680 7 competitor-a.com 2.3
buy [category] online discount 550 4 competitor-d.co.uk 1.9

The top 5 opportunities alone represent ~4,080 clicks you're currently missing. "best [category] deals 2026" is particularly notable - 8 competitors are active there.

These are all high-intent commercial terms. Adding them to your campaigns could capture significant additional traffic.

Note

Search term opportunities are limited to the last 30 days of data.

5. AI Overview Tracking

What you ask:

How often are AI Overviews appearing for our search terms? Which terms trigger them most?

Tools the agent may use:

  1. get_ai_overview(report_type="overview") for frequency trends
  2. get_ai_overview(report_type="search_terms", order_by="frequency", page_size=10) for the most affected terms

What you get:

AI Overview Appearances (last 6 weeks):

AI Overviews are appearing on approximately 34% of your tracked search terms, up from 28% at the start of March.

Weekly Trend:

Week AI Overview Frequency
Mar 2 28.3%
Mar 9 29.1%
Mar 16 30.5%
Mar 23 31.8%
Mar 30 33.2%
Apr 6 34.1%

Top Terms with AI Overviews:

Search Term AI Overview Frequency Est. Impressions
what is [category] 92% 15,400
[category] vs [alternative] 88% 8,900
best [category] for [use case] 85% 12,200
how to choose [category] 82% 6,700
[category] buying guide 79% 5,100

Informational and comparison queries are most heavily affected. These are the terms where your paid ads may be pushed below the fold by AI-generated answers. Consider adjusting your strategy - they may require different creative approaches or bid adjustments to maintain visibility.

Note

AI Overview data requires start_date on or after 2025-07-31.

6. AI Overview Deep Dive (Premium)

What you ask:

How is our brand being cited in AI Overviews? What's the sentiment, and how does it affect our CTR?

Tools the agent may use:

  1. get_ai_overview_content(report_type="content") for citation frequency, sentiment, and themes
  2. get_ai_overview_content(report_type="competitors") for top cited domains
  3. get_ai_overview_impact(report_type="impact") for CTR/CPC with vs without AI Overview
  4. get_ai_overview_impact(report_type="search_terms", bucket_label=["100"]) to drill into fully-affected terms

What you get:

AI Overview Content Analysis (last 30 days):

Your brand is cited in 41% of AI Overviews across your tracked search terms.

Sentiment Breakdown:

Sentiment Share
Favourable 38%
Neutral 29%
Comparative Balanced 18%
Unfavourable 10%
Inconclusive 5%

Top Themes in AI Overviews:

Theme Share
Comparison 32%
Review 25%
How-to 19%
FAQ 14%
Problem Solving 10%

Top Cited Domains:

Domain Citation Share
yourdomain.com 41%
competitor-a.com 28%
competitor-b.co.uk 15%
review-site.com 9%
news-outlet.com 7%

CTR/CPC Impact:

Metric With AI Overview Without AI Overview
CTR 2.8% 4.1%
CPC $1.20 - $1.85 $0.95 - $1.40

AI Overviews reduce your CTR by approximately 1.3 percentage points and increase CPC. The 412 search terms with 100% AI Overview frequency are most affected - consider adjusting bids or creative for those terms.

Note

AI Overview Content and Impact are premium features. They default to a rolling 30-day window when no dates are provided, but you can pass start_date and end_date to narrow the range (must be within the last 30 days).

7. LLM Performance Analysis

What you ask:

How is our brand performing in ChatGPT and Perplexity? Which domains are cited most, and how healthy are our prompts?

Tools the agent may use:

  1. get_llm_prompts(report_type="prompt_groups") to discover available AEO/organic prompt groups
  2. get_llm_performance(report_type="domain_trends", segment_by=["engine"]) for citation trends by engine
  3. get_llm_performance(report_type="domain_performance") for per-domain scores
  4. get_llm_prompt_metrics(report_type="prompts", page_size=10) for per-prompt health status

What you get:

LLM Domain Performance (last 30 days):

Your domain is cited in LLM responses across both ChatGPT and Perplexity. Here are the top-performing domains:

Domain Performance Score Citation Share Avg Position
competitor-a.com 87.3 32.1% 2.1
yourdomain.com 72.5 24.8% 2.8
competitor-b.co.uk 58.9 18.3% 3.4
review-site.com 41.2 12.5% 4.1
news-outlet.com 23.8 7.2% 5.3

ChatGPT vs Perplexity:

Engine Your Citation Share Your Avg Position
ChatGPT 28.4% 2.5
Perplexity 19.1% 3.2

Your share of ChatGPT citations (28.4%) is larger than your share of Perplexity citations (19.1%), and your average position is better there too.

Prompt Health Status:

Prompt Group Engine Health Brand Mentioned Competitors
best [category] brands Brand chatgpt STRONG Yes competitor-a.com
[category] comparison Generic chatgpt ATTENTION Yes competitor-a.com, competitor-b.co.uk
cheapest [category] Price perplexity AT_RISK No competitor-c.com
[category] reviews Reviews chatgpt STRONG Yes review-site.com

3 out of 4 prompts show your brand is mentioned, but the "cheapest [category]" prompt on Perplexity is AT_RISK - your brand isn't mentioned at all. Consider strengthening your price-competitive content to improve visibility on that prompt.

Note

Per-prompt citations come from report_type="prompts_v2" and group-level metrics from report_type="prompt_groups", both over any date range. Health and mention scoring comes from report_type="prompts", which is capped at the last 30 days. Both per-prompt reports always segment by engine, so you get separate rows per engine automatically. Google AI Mode (googleai) is available on these organic reports but is not in the default engine list.

8. AI Ads Intelligence Visibility

What you ask:

How are we performing in paid LLM ad placements? Show me overall ad presence, the top competitors, and where we have gaps or greenfield prompts.

Tools the agent may use:

  1. get_llm_ad_prompts() to confirm AI Ads prompts are configured for the account (empty result = AI Ads not in use; stop here)
  2. get_ai_ads_intelligence(report_type="performance_trends", segment_by=["engine"]) for ad presence trends per engine
  3. get_ai_ads_intelligence(report_type="advertiser_share_trends", max_number_of_domains=5) for share of ads
  4. get_ai_ads_intelligence(report_type="prompts_analysis", prompt_status="gap") for gap prompts
  5. get_ai_ads_intelligence(report_type="prompts_analysis") then filter for is_greenfield=true for uncontested wins

What you get:

AI Ads Intelligence Presence (last 14 days, by engine):

Engine Ad Presence Rate Prompts With Ads Total Prompts Competitors Detected Top Competitor
chatgpt 41.2% 38 / 92 92 12 competitor-a.com (24.1%)
googleai 28.7% 26 / 92 92 9 competitor-a.com (19.4%)

The brand appears in 41% of ChatGPT scrapes but only 29% of Google AI - a 12pp gap. ChatGPT has more competitor noise (12 distinct competitors) but the brand also wins more often there.

Share of Ads - Top 5 Competitors (last 14 days, aggregated engines):

Advertiser Domain Share of Ads
Your Brand yourdomain.com 22.8%
Competitor A competitor-a.com 21.7%
Competitor B competitor-b.co.uk 14.2%
Competitor C competitor-c.com 9.5%
Competitor D competitor-d.com 6.1%

The brand row is always included alongside the top 5 competitors. The brand and competitor-a.com are neck-and-neck.

Gap Prompts (prompt_status="gap", ordered by top_competitor_rate):

Prompt Your Detection Top Competitor Their Rate Competitors
"cheapest [category] uk" - competitor-c.com 78% 4
"[category] discount code" - competitor-d.com 65% 3
"best [category] under £100" - competitor-a.com 54% 5

On these prompts the your_ads_detection_rate field is omitted from the response (the key is absent) - the brand had zero detections. The dash above represents that omission, not a zero value. In context the practical meaning is the same: the brand is invisible on these prompts.

Greenfield Prompts (is_greenfield=true):

Prompt Your Detection Rate
"yourbrand outlet store" 92%
"yourbrand member discount" 87%
"yourbrand return policy" 81%

These prompts have no top_competitor field in the response - no competitors were detected at all (is_greenfield: true is set explicitly). The brand wins these uncontested. Defend these positions; competitor-a.com is the most likely future entrant based on its activity elsewhere.

Note

Engines are chatgpt and googleai. See Tool Reference → How to read AI Ads Intelligence responses for the field-omission and zero-fill rules. To see the creatives behind these rates, use get_llm_ad_library - and read How to read LLM Ad Library responses first, because its trend is not zero-filled.

9. Reading Competitor Ad Copy in LLM Answers

get_ai_ads_intelligence tells you how often advertisers appear. get_llm_ad_library shows you what they actually said. Advertisers are identified by domain, not display name.

What you ask:

What ad copy are our competitors running inside ChatGPT and Google AI answers? Show me the most-detected ones, and anything new that has just appeared.

Tools the agent may use:

  1. get_llm_ad_library(report_type="ads", advertiser_scope="competitors", page_size=10) for the most-detected competitor text creatives
  2. get_llm_ad_library(report_type="ads", advertiser_scope="competitors", state="new") for creatives that have just entered the market
  3. get_llm_ad_library(report_type="plas", advertiser_scope="competitors", engine=["googleai"]) for competitor shopping units

What you get:

Top competitor text creatives (last 30 days, by detections):

Advertiser Domain Engine Headline Body Detections Prompts State
Competitor A competitor-a.com googleai Compare [Category] Plans - Free Switching Switch in under 10 minutes. No exit fees, no downtime. 412 34 live
Competitor A competitor-a.com chatgpt Compare [Category] Plans - Free Switching Switch in under 10 minutes. No exit fees, no downtime. 287 29 live
Competitor C competitor-c.com googleai Cheapest [Category] in the UK Price-match promise. Rated 4.8/5 by 12,000 customers. 198 21 live
Competitor B competitor-b.co.uk chatgpt [Category] Made Simple - 30-Day Trial Cancel any time. Setup included. UK support team. 143 18 quiet

The same competitor-a.com creative runs on both engines and is returned once per engine - 412 + 287 is not a unique-creative count, it is that one creative's total across two engines.

Newly appeared (state="new", first seen within 7 days of the range end):

Advertiser Domain Engine Headline First Seen Detections
Competitor D competitor-d.co.uk googleai Switch and Save £120 a Year Aug 12 61
Competitor A competitor-a.com googleai [Category] Bundle - Two for One Aug 14 38

Competitor shopping units:

Advertiser Domain Product Title Price Was Tag Detections
Competitor C competitor-c.com [Product] Pro 512GB - Midnight £899.00 £1,049.00 Sale 156
Competitor A competitor-a.com [Product] Standard 256GB £649.00 - - 94

competitor-a.com is running the same "free switching, no exit fees" angle on both engines, and has just launched a bundle creative on Google AI. competitor-b.co.uk reads quiet - it is still in the data but has stopped appearing, so its trial offer is likely retired.

10. Tracing a Single Creative

What you ask:

Take that competitor-a.com "free switching" ad. Which of our prompts is it winning on, how has it trended, and where does it send people?

Tools the agent may use:

  1. get_llm_ad_library(report_type="ads", search=["free switching"], advertiser=["competitor-a.com"]) to get the creative_id
  2. get_llm_ad_library(report_type="prompts", creative_id="a7f39c02e1b4") for the prompts it ran on
  3. get_llm_ad_library(report_type="trend", creative_id="a7f39c02e1b4") for its detection history
  4. get_llm_ad_library(report_type="destinations", creative_id="a7f39c02e1b4") for the landing URLs

What you get:

Creative a7f39c02e1b4 - competitor-a.com, googleai, live "Compare [Category] Plans - Free Switching" / "Switch in under 10 minutes. No exit fees, no downtime." First seen Jun 3, last seen Aug 18, 412 detections across 34 prompts, best position 1, average position 1.8.

Prompts it appeared on (top 5 by detections):

Prompt Detections Best Position Avg Position
"best [category] provider uk" 74 1 1.4
"how to switch [category] provider" 61 1 1.6
"cheapest [category] deals" 48 2 2.1
"[category] with no exit fees" 39 1 1.2
"compare [category] plans" 31 2 2.3

Detection trend (weekly):

Week Starting Detections Prompts Avg Position
Jul 19 58 19 2.4
Jul 26 71 23 2.0
Aug 9 134 30 1.7
Aug 16 149 33 1.6

Where it lands:

Destination URL Host Detections First Seen Last Seen
https://www.competitor-a.com/switch?utm_source=ai&cid=8842 www.competitor-a.com 261 Jun 3 Aug 18
https://www.competitor-a.com/switch?utm_source=ai&cid=9107 www.competitor-a.com 158 Jul 9 Aug 18
https://offers.competitor-a.com/no-exit-fees offers.competitor-a.com 87 Jul 27 Aug 18

This creative is scaling: detections rose from 58 to 149 a week while average position improved from 2.4 to 1.6. It concentrates on switching intent - "no exit fees" wins position 1.2 on average - and the switching page carries the traffic. Two things to read carefully here. The weekly trend has no row for the week of Aug 2: the trend is not zero-filled, so a missing bucket means no detections were recorded, and you have to notice the gap in the date sequence yourself rather than read four consecutive rows as four consecutive weeks. And the destinations total (506) is larger than the creative's 412 detections, because a landing URL is recorded against the creative with no record of the prompt that produced it - so it counts every prompt the creative was answered on, not only the prompts you track. Never present it as a share of the creative's detections.

The first two URLs are the same page with different tracking IDs - group on landing_path (/switch) rather than the raw URL.

Note

report_type="prompts", "trend" and "destinations" all need a creative_id taken from an ads or plas row. state is measured against your end_date, not today, so a historical range returns the states as of that range. See Tool Reference → How to read LLM Ad Library responses for the full set of traps.