Adthena

Get search term overlap analysis between your domain and each competitor. Shows shared search terms, overlap ratios, and click estimates per competitor. Response fields: competitor, device, ad_type, location_name, your_relevant_search_terms, relevant_search_terms, shared_relevant_search_terms, competitor_only_search_terms, overlap_ratio (0-1), competitor_coverage_ratio (0-1), jaccard_similarity (0-1), estimated_clicks, shared_terms_estimated_clicks. order_by options: "shared_relevant_search_terms" (default), "relevant_search_terms", "competitor_only_search_terms", "overlap_ratio", "competitor_coverage_ratio", "jaccard_similarity", "estimated_clicks", "shared_terms_estimated_clicks". Use min_shared_terms=0 to include all competitors. Set pairwise=true with exactly 2 or 3 domains in the competitor filter to additionally receive a top-level `pairwise` block with competitor-to-competitor intersection counts: each competitor's own term-set size, every pairwise intersection and, for 3 competitors, the triple intersection - enough to draw a proportional Venn diagram. pairwise=true with any other competitor count is rejected with a 400. See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segment_by details.

get_competitor_overlap

Get time series showing the number of unique competitors per time period. Tracks how competitive intensity changes over time - spot new entrants or leavers. Response: list of segments, each with time_series of {date, competitor_count}. No pagination - returns all data, ordered by date ascending. See docs://date-rules for date and time_period handling. See docs://data-access for segment_by details.

get_competitor_trends

Get the actual ad creatives detected in LLM answers: the ad copy, shopping units, advertisers, landing URLs, and per-creative detection history behind AI Ads Intelligence. This is the creative-level view of the same PAID AD placements that get_ai_ads_intelligence() reports on in aggregate. Use get_ai_ads_intelligence() for rates and share ("how visible are we"); use this tool for the creatives themselves ("what are they actually saying, and where does it point"). Engines are "chatgpt" and "googleai" (NOT "perplexity") - this is not the organic-citation surface covered by get_llm_performance(). Requires the account to have llm_ads_enabled; per-engine entitlement flags further gate which engines respond - disabled engines are silently dropped, and a call with no entitled engines returns 403. Dates in YYYY-MM-DD format. end_date must not be later than yesterday (today's data is not yet available). report_type options: - "ads" (default): the text ad creatives, one row per (creative, engine, advertiser). Fields: creative_id, engine, advertiser, advertiser_domain, is_own_brand, headline, body, headline_length, image_id, image_url, sample_url, landing_path, state, first_seen, last_seen, detections, prompt_count, days_seen, best_position, avg_position. Paginated. - "plas": the shopping (PLA) unit creatives, same grain as "ads". Fields: creative_id, engine, advertiser, advertiser_domain, is_own_brand, title, price, old_price, tag, headline_length, image_id, image_url, sample_url, landing_path, state, first_seen, last_seen, detections, prompt_count, days_seen, best_position, avg_position. The copy fields are title/price/old_price/tag rather than the headline/body of a text ad. Paginated. - "prompts": the prompts a single creative appeared on, one row per prompt. Fields: prompt, detections, days_seen, best_position, avg_position. Requires creative_id. Paginated. - "trend": a single creative's detections over time, one row per period bucket. Fields: date, detections, prompt_count, best_position, avg_position. Requires creative_id. Paginated. - "destinations": the landing URLs a single creative carried. Fields: destination_url, destination_domain, destination_host, detections, first_seen, last_seen. Requires creative_id. Paginated. creative_id is a path parameter on the three detail report types and comes from the creative_id field of an "ads" or "plas" row. It is ignored for the two list report types. Filters (the two lists only): advertiser matches on either advertiser name or domain. advertiser_scope restricts to your own brand's creatives ("own"), your competitors' ("competitors"), or everything ("all", default). state restricts to one lifecycle state, or "all" (default). search (the two lists only) is free-text over the creative copy and advertiser fields ("ads": headline, body, advertiser, advertiser_domain; "plas": title, advertiser, advertiser_domain). It is repeatable and repeats NARROW rather than widen: terms are ANDed, so search=["laptop", "monitor"] returns only creatives matching BOTH terms. Each individual term still matches if ANY of the searched fields contains it. prompt / excluded_prompt / prompt_group / excluded_prompt_group narrow the account's tracked prompt set, so they filter the lists and the "prompts" / "trend" report types identically. They are NOT accepted on "destinations" (see the destinations caveat below) and are not sent for it. competitor / excluded_competitor / competitor_group / excluded_competitor_group narrow the ADVERTISER DOMAIN (advertiser_domain) on the same report types as the prompt filters - the two lists plus "prompts" and "trend" - and are likewise not sent for "destinations". competitor takes domains; competitor_group takes the account's competitor group names (the same groups used by get_market_share() and get_ads(); discover them via get_account_settings()). They are literal: the account's own domain is a filterable domain like any other, so a selection that does not contain it hides the brand's own creatives. The domains that can match are the LLM-relevant competitors - every domain ever seen advertising or cited on the account's tracked prompts, NOT the Google-SERP relevant competitors used elsewhere. These compose with advertiser (name-or-domain match) and advertiser_scope (own / competitors / all), which stay unchanged; the applied values are echoed under filters.competitor / filters.excluded_competitor / filters.competitor_group / filters.excluded_competitor_group. Sorting - order_by is per report_type, and omitting it takes the endpoint's own default: - "ads" / "plas": "detections" (default), "prompt_count", "days_seen", "first_seen", "last_seen", "best_position", "avg_position", "advertiser", "headline" (on "plas" this sorts the product title). - "prompts": "detections" (default), "prompt". - "trend": "date" only. - "destinations": "detections" (default), "destination_url". Omitting order_direction also takes the endpoint's own default, which is "desc" everywhere EXCEPT "trend", which defaults to "asc" so the series reads oldest to newest. Pass it explicitly only when you want to override that. Default page_size is 50 (max 1000). Pass page_size=0 to fetch all results - creative lists can be large, so prefer paging or a tighter date range over pulling everything. DATA INTERPRETATION - how to read the response (fields, omissions, semantics): - The API NEVER returns JSON `null`. Undefined values are OMITTED FROM THE RESPONSE (the key is absent), not serialized as `null`. Detect "undefined" by checking for key absence. - Grain: list rows are one per (creative, engine, advertiser DOMAIN) - the domain is the advertiser identity here, and `advertiser` is a display name picked off the same rows. The SAME creative appears once per engine it ran on, so do not sum detections across rows and call it a unique-creative count, and group on `advertiser_domain` rather than `advertiser` when rolling rows up. - `days_seen` is a SPAN, not a count of active days: inclusive days between the first and last observation. A creative seen once in January and once in June has days_seen of about 150, not 2. On list rows the span covers the creative's whole observed lifetime; on "prompts" rows it is measured inside the requested window (weekly and monthly observations count through the end of their last bucket, clamped to end_date). - `first_seen` / `last_seen` on list rows likewise span the creative's whole observed lifetime, NOT the requested range. A creative can therefore report a last_seen before your start_date while still returning detections inside the range. - `state` is measured against the END of the requested date range, not against today: "new" = first observed within 7 days of that end, "quiet" = last observed more than 7 days before it (still in the data, but it has stopped appearing), "live" = neither. Because it derives from the lifetime first_seen / last_seen, a creative CAN read "quiet" inside a range it was detected in. Query a historical range and you get the states as of that range. - `best_position` is the best (lowest) 1-based rank achieved; `avg_position` is detection-weighted, to 2 decimal places. Both are omitted when no rank was captured. Lower is better for each. - `is_own_brand` is true when the advertiser's domain matches your account's domain. It is what advertiser_scope filters on. - `advertiser` and `advertiser_domain` can be empty strings - the source data carries no advertiser for that row. Treat that as "unattributed", not as a lookup failure. - `sample_url` is the creative's MOST-DETECTED landing URL over the range, exactly as observed. Per-impression tracking tokens make any single URL a sample of where the creative points rather than a stable identifier - use report_type="destinations" for the full set. `landing_path` is that URL's path with scheme, host, query string and fragment removed, which is the field to group on. Both are omitted when no destination was captured. - `image_id` is a content-addressed SHA-256 digest, stable for identical image bytes (so it is safe to cache against); `image_url` is the absolute Adthena-served URL. Both are omitted when the creative has no image. `headline_length` is 0, not omitted, when the creative carries no headline. - "trend" is NOT zero-filled: buckets with no detections are simply absent from the response. This is the opposite of get_ai_ads_intelligence()'s time_series, which zero-fills every day. Do not read a missing bucket as a zero without checking the date sequence yourself. - "destinations" detections COUNT ON A WIDER BASIS and do not sum to the creative's `detections` on the list row. A landing URL is recorded against the creative alone with no record of the prompt that produced it, so its detections cover every prompt the creative was answered on, while the list row and the "prompts" / "trend" report types count only the prompts your account tracks. Expect the destinations total to be the LARGER of the two, and never present it as a share of the creative's detections. This is also why the prompt filters do not apply there. - Bucket dates follow time_period: daily rows carry the day, weekly rows the Sunday week-start, monthly rows the first of the month. Data depth differs by time_period: the daily tables hold roughly the last month, the weekly tables the last 13 months, and the monthly tables the full history. A range reaching past the chosen period's depth returns only the rows that exist, so pick a coarser time_period for long histories. Because weekly and monthly rows are stored on their bucket-start date, a range containing no bucket start returns no rows at all - a "monthly" query over a mid-month week is an empty result, not an error. These endpoints support only the prompt, competitor and creative filters above - there is no device, ad_type, search_term, adwords_campaign, location or segment_by parameter. Location is fixed to the account's own market. Use get_llm_ad_prompts() to discover the prompts and prompt groups available for filtering. See docs://date-rules for date and time_period handling. See docs://data-access for pagination. See docs://concepts for metric definitions. See docs://workflows section "AI Ads Intelligence Visibility Analysis" for how this fits the wider analysis.

get_llm_ad_library

List AI Ads prompts and prompt groups configured for an account. This is the discovery tool for the AI Ads Intelligence surface - call it first to see what ad prompts and prompt groups exist before querying ad metrics with get_ai_ads_intelligence(). No date range or engine parameters needed. AI Ads prompts are customer-managed and a different surface from the AEO/organic prompts returned by get_llm_prompts(). An **empty result** means the account has no AI Ads prompts configured - treat this as the gate signal that AI Ads Intelligence is not in use for this account. By default (is_all=false) this returns only **currently active** prompts/groups; soft-deleted entries are excluded. There is no date window - listings describe current account configuration. Pass is_all=true to also include soft-deleted entries (those with a valid_to set). Use is_all=true to reconcile discovery output with get_ai_ads_intelligence(), which already counts prompts for the days they were alive, so a metric window may reference a prompt that the default (active-only) listing omits. report_type options: - "prompt_groups": List AI Ads prompt groups with their associated locations. - "prompts": List individual AI Ads prompts with their group name and locations. Default page_size is 0 (all results). LLM data is typically under 500 items. Pass a specific page_size if you need smaller pages. Response fields (prompt_groups): group_name, locations, valid_to (null while the group still has any active prompt, otherwise the latest deletion time among its prompts). Response fields (prompts): prompt, group_name, locations, valid_to (null while the prompt is active, otherwise its deletion timestamp), created_at, modified_at, modified_by (email of the last modifier). order_by for prompt_groups: "group_name" only. order_by for prompts: "prompt", "group_name". Use the returned group names and prompt texts as filter values in get_ai_ads_intelligence().

get_llm_ad_prompts

Get LLM domain performance data: citation trends and per-domain metrics from ChatGPT, Perplexity and Google AI Mode. METRIC SEMANTICS - read before reporting numbers. citations_frequency is a SHARE, not a rate: the domain's slice of all citations across tracked domains (0-1), not how often the domain appears per response. Report it as "share of citations", never as "citation frequency of responses". Citations count cited source LINKS; they are unrelated to brand MENTIONS in answer text (see get_llm_prompt_metrics for mention metrics). Never present a mention share as a citation share or vice versa. Any date range; `time_period` selects the grain. end_date must not be later than yesterday (today's data is not yet available). Dates in YYYY-MM-DD format. See docs://date-rules for time_period handling; the resolved grain is echoed as filters.time_period in the response, so read it rather than assuming the `date` values are consecutive days. ENGINES: "chatgpt", "perplexity" and "googleai" (Google AI Mode). The default is chatgpt + perplexity, so AI Mode is only included when you ask for it explicitly - add "googleai" to `engine` whenever the question is about AI Mode or about total organic visibility. Engines the account is not entitled to, or that are switched off for it, are silently dropped from the request and the response's filters.engine reports which ones actually answered; a call naming only unavailable engines returns 403. Compare filters.engine against what you asked for before reporting a total, because a smaller engine set means a smaller number. Soft-delete behaviour: includes any prompt that was active during any part of the requested window. A prompt deleted mid-window contributes data for the days it was alive, then disappears - so historical trends can reference prompts no longer returned by get_llm_prompts(). The `prompt` and `prompt_group` filters follow the same rule: a prompt that was already deleted before the window started cannot be matched, even by exact name. report_type options: - "domain_trends": Time series of top-cited domains in LLM responses. NOT paginated - returns all selected domains (up to max_number_of_domains) with full daily time series. Use max_number_of_domains (1-100, default 10) and primary_dimension to control which domains are selected. - "domain_performance": Per-domain performance table with scores, citation share, and position metrics. Default page_size is 0 (all results). LLM data is typically under 500 items. Pass a specific page_size if you need smaller pages. primary_dimension (domain_trends only): "frequency" (default) ranks domains by citation share (the citations_frequency field); "average_position" ranks by average position (lower = better). Response fields (domain_trends): each data entry has just two keys - engine (the engine label) and a nested competitors[] list. There is no segments key. Each competitors[] entry carries competitor, citations_frequency (share of all citations, 0-1), avg_position, performance_score (0-100), avg_position_citation, avg_position_link, and its own daily time_series (date, citations_frequency, avg_position). Response fields (domain_performance): competitor, engine, performance_score (0-100), citations_frequency (share of all citations, 0-1), avg_position, avg_position_citation, avg_position_link. order_by for domain_performance: "competitor", "performance_score", "citations_frequency", "avg_position", "avg_position_citation", "avg_position_link". segment_by=["engine"] splits results per LLM engine (ChatGPT vs Perplexity). Default (empty) aggregates across engines. Filtering: prompt / excluded_prompt / prompt_group / excluded_prompt_group narrow the tracked prompt set (use get_llm_prompts() to discover them). competitor / excluded_competitor / competitor_group / excluded_competitor_group narrow the CITED DOMAINS: competitor takes domains, competitor_group takes the account's competitor group names (the same groups used by get_market_share() and get_ads(); discover them via get_account_settings()). The filters are literal - the account's own domain is a filterable domain like any other, so a selection that does not contain it hides the brand row/series, and any brand-relative figure is computed over the filtered domain set. The domains that can match here are the LLM-relevant competitors: every domain ever seen cited or advertising on the account's tracked prompts, NOT the Google-SERP relevant competitors used elsewhere, so a Google competitor that has never been cited by an LLM matches nothing. There are no device, ad_type, search_term, or adwords_campaign filters. The applied values are echoed under filters.competitor / filters.excluded_competitor / filters.competitor_group / filters.excluded_competitor_group. filtering_options controls how the competitor / competitor_group selection interacts with the metrics. "relative" (default) applies the selection BEFORE aggregation, so citations_frequency and performance_score are recomputed over the selected domain set and the selected shares sum to 1. "absolute" computes every metric over the whole market and only filters which domain rows are returned, so shares keep their whole-market values and do not sum to 1. Exclusions (excluded_competitor / excluded_competitor_group) apply in both modes. Ignored when no competitor filters are given; sent for both report types.

get_llm_performance

Get LLM prompt-level mention, citation, and health metrics. MENTIONS ARE NOT CITATIONS. A mention counts the brand's NAME appearing in AI answer text; a citation counts a cited source LINK pointing to a domain. brand_share_of_mentions is a text-mention share and says nothing about citations - a brand can score 100% share of mentions while receiving few or no citations. For the brand's share of citations use brand_share_of_citations (prompt_groups report), or get_llm_performance(report_type= "domain_performance") for per-domain citation share. Never report one metric using the other's name. DATE RANGE: any range for every report_type; `time_period` selects the grain (see docs://date-rules), and the resolved value is echoed as filters.time_period. end_date must not be later than yesterday (today's data is not yet available). Dates in YYYY-MM-DD format. ENGINES: "chatgpt", "perplexity" and "googleai" (Google AI Mode). The default is chatgpt + perplexity, so AI Mode is only included when you ask for it explicitly - add "googleai" to `engine` whenever the question is about AI Mode or about total organic visibility. Engines the account is not entitled to, or that are switched off for it, are silently dropped from the request and the response's filters.engine reports which ones actually answered; a call naming only unavailable engines returns 403. Compare filters.engine against what you asked for before reporting a total, because a smaller engine set means a smaller number. Soft-delete behaviour: includes any prompt that was active during any part of the requested window. A prompt deleted mid-window contributes data for the days it was alive, then disappears - so historical metrics can reference prompts no longer returned by get_llm_prompts(). The `prompt` and `prompt_group` filters follow the same rule: a prompt that was already deleted before the window started cannot be matched, even by exact name. report_type options: - "prompt_groups": Per-prompt-group metrics - unique domain count and total citation count (citation-based), plus brand_share_of_mentions (text mentions, computed over the requested range at every grain) and brand_share_of_citations (cited links). segment_by=["engine"] available to split by engine. - "prompts": THE per-prompt report, always segmented by engine. Citation breadth AND mention metrics over the requested range at any grain: cited_domain_count/cited_domains, total_mentions, total_brand_mentions, brand_mentioned, brand_share_of_mentions, the framing counters, mentioned_competitors with mentioned_competitor_domains (positionally paired), account_brand_name, top_cited_urls. Rows are the union of cited and mentioned prompts. The CLASSIFICATION fields alone (category, scenarios, health_status) describe the current health window (the latest scored trailing week), independent of the requested range: they appear only when the resolved time_period is "daily" and are ABSENT (omitted, not null) on weekly/monthly responses - check filters.time_period before concluding a prompt is unscored. Default page_size is 0 (all results). LLM data is typically under 500 items. Pass a specific page_size if you need smaller pages. Response fields (prompt_groups): group_name, engine, unique_domain_count, total_citation_count, brand_share_of_mentions (share of brand-name text mentions, 0-1), brand_share_of_citations (share of cited source links pointing to the account's domain, 0-1). Response fields (prompts): prompt, group_name, engine, cited_domain_count (unique domains citing this prompt on this engine), cited_domains, total_mentions, total_brand_mentions, brand_mentioned, brand_share_of_mentions, recommended_count, informational_count, cautionary_count, competitor_recommended_count, mentioned_competitors with mentioned_competitor_domains (positionally paired), account_brand_name, top_cited_urls - all over the requested range - plus, on daily resolution only (current health window), category, scenarios, health_status (AT_RISK / ATTENTION / STRONG). A prompt's overall citation breadth across engines is the UNION of its rows' cited_domains, not the sum of their cited_domain_count values, which would double count any domain cited on more than one engine. order_by for prompt_groups: "group_name", "unique_domain_count", "total_citation_count". order_by for prompts: "prompt", "group_name", "cited_domain_count". Note: If a prompt belongs to multiple groups, it appears as separate rows - one per (prompt, group_name, engine) combination. Use get_llm_prompts() to discover available prompts and prompt groups before querying metrics. These endpoints only support prompt-based filtering - no device, ad_type, search_term, competitor, or adwords_campaign filters.

get_llm_prompt_metrics

List AEO (organic) LLM prompts and prompt groups configured for an account. This is the discovery tool for the AEO Performance surface - call it first to see what organic prompts and prompt groups exist before querying metrics with get_llm_prompt_metrics() or get_llm_performance(). No date range or engine parameters needed. Prompts are customer-managed. This tool returns organic prompts only - for the AI Ads surface use get_llm_ad_prompts(). By default (is_all=false) this returns only **currently active** prompts; soft-deleted prompts are excluded. There is no date window - listings describe current account configuration. Pass is_all=true to also include soft-deleted prompts (those with a valid_to set). Use is_all=true to reconcile discovery output with get_llm_prompt_metrics() / get_llm_performance(), which already count prompts for the days they were alive, so a metric window may reference a prompt that the default (active-only) listing omits. report_type options: - "prompt_groups": List prompt groups with their associated locations. - "prompts": List individual prompts with their group name and locations. Default page_size is 0 (all results). LLM data is typically under 500 items. Pass a specific page_size if you need smaller pages. Response fields (prompt_groups): group_name, locations, valid_to (null while the group still has any active prompt, otherwise the latest deletion time among its prompts). Response fields (prompts): prompt, group_name, locations, valid_to (null while the prompt is active, otherwise its deletion timestamp), created_at, modified_at, modified_by (email of the last modifier). order_by for prompt_groups: "group_name" only. order_by for prompts: "prompt", "group_name". Use the returned group names and prompt texts as filter values in get_llm_performance() and get_llm_prompt_metrics().

get_llm_prompts

List all Adthena accounts you have access to. IMPORTANT: Call this tool first before using any other Adthena tool. If there are multiple accounts, you MUST present the list to the user and ask them which account to use. Do NOT proceed with queries until the user has confirmed their choice. Never query all accounts unless the user explicitly asks for it. Returns a list of accounts with account_id, domain, location_code, location_name, and parent_account_id. **Filtering:** Use `domain` and/or `location` to narrow results. Both perform case-insensitive substring matching (e.g., domain="nike" matches "nike.com" and "nike.co.uk"). When the full list is large, always filter to keep results manageable. **Location hierarchy:** Accounts with a non-null `parent_account_id` are child locations within a hierarchy. To query data across multiple locations efficiently, use the parent account and pass the desired location names via the `location` parameter - this returns all locations' data in a single call instead of making separate requests per child account. **Missing accounts:** Only accounts with API access enabled are listed here. If an expected account is not shown, it likely does not have API access enabled. The user should contact their Adthena account manager to verify and enable API access for that account. Args: domain: Filter accounts by domain (case-insensitive substring match). location: Filter accounts by location name (case-insensitive substring match).

list_accessible_accounts

Get Local Service Ads data: how often Google showed Local Service Ads for the account's search terms, and which businesses took those spots. Local Service Ads are the "Google Guaranteed" / "Google Screened" listings above the text ads, used by local trades and professional services. An advertiser here is a BUSINESS NAME, not a domain - so competitor and competitor-group filters do not apply to this tool and are not accepted. The data does NOT distinguish Google Guaranteed from Google Screened: there is no badge field, only the business name. Guaranteed covers home services and Screened covers professional ones such as legal and medical, so the vertical is a strong hint, but do not state which badge a listing carries. Every row is a Local Service Ad and carries ad_type "lsa". There is no ad type to choose and no ad_type argument: this tool returns one result type and nothing else. It cannot answer how Local Service Ads compare with text ads, Shopping ads or organic results - say so rather than reaching for another tool's figures, whose denominators are not the same. `is_whole_market` (default true) keeps the whole tracked term set. Setting it false narrows to terms where your own DOMAIN appeared, which is a text-ad notion and rarely what you want here, since a Local Service Ads advertiser is not a domain. To narrow the terms, use search_term or search_term_group. `segment_by` chooses the grain of the rows you get back (default [] - one aggregate row): - [] - one row for the whole window - ["date"] - a time series at the requested time_period - ["business_name"] - one row per advertiser (reads the per-advertiser data) - ["search_term_group"] or ["search_term"] - per group or per term - combine them freely, e.g. ["date", "business_name"] Response fields: date, device, ad_type, search_term, search_term_group, location_name, business_name, weighted_appearances, weighted_total_appearances, weighted_scrape_count, weighted_advertiser_scrape_count, weighted_rank_sum, best_rank, periods_seen, last_seen. THE TWO SCRAPE COUNTS ARE NOT INTERCHANGEABLE. weighted_scrape_count counts every tracked search and is the frequency denominator; it is null when you segment by business_name. weighted_advertiser_scrape_count counts only the searches ONE business was measured on and is null everywhere else, because the per-advertiser data holds a row solely where that business appeared. That is why a per-advertiser rate is unaffected by the 8 Oct 2026 measurement update while the result-type rates are not. weighted_rank_sum and best_rank are null unless you segment by business_name: the other data records that Local Service Ads appeared, not where they sat. periods_seen and last_seen report presence rather than volume, and are returned at every level. A dimension you did NOT segment by reports the set of values the row covers as a comma-separated string ("desktop, mobile"), the same convention as the other tools; a dimension the underlying data does not carry for that grain is null. Segmenting by business_name sets weighted_total_appearances to null, because that data counts a business once per search. THE MEASURES ARE SUMS, NOT RATES - derive the figures you need from them: - Frequency, the share of tracked searches where the result appeared: summed weighted_appearances / summed weighted_scrape_count - Local Service Ads per search, counting every appearance rather than just the first: summed weighted_total_appearances / summed weighted_scrape_count - A business's market share of all Local Service Ads: that business's weighted_appearances divided by the total across every business. Use page_size=0 for this: on the default 50-row page the denominator is the page, not the market, and the shares come out far too high - FREQUENCY NEEDS A READ WITHOUT business_name. Dividing the per-advertiser sums by each other tells you how often one business shows among the searches it competes on, not how often Local Service Ads appear: on one account over a clean week that reads 40.74% against a real 0.0076%. If you have advertiser rows and need frequency, read again without business_name. - A business's average position: summed weighted_rank_sum / summed weighted_appearances. NOT over weighted_scrape_count, which counts searches the business was absent from and returns a plausible-looking position that is wrong - often below 1, which is not a possible position. best_rank is the one measure here that is not additive: combine it with MIN, never a sum or an average The sums are additive, so you can aggregate rows yourself: summing a segmented result reconstructs the unsegmented one exactly. Rates are NOT additive - never average a frequency across rows, recompute it from the sums, or you will get a subtly wrong answer. THREE GRAINS DO NOT SUM BACK, each for its own reason: - business_name measures something else. Summing per-business appearances counts every Local Service Ad shown, so it reconstructs the unsegmented weighted_total_appearances, not weighted_appearances (searches carrying at least one). An advertiser's share of all Local Service Ads is still exactly right, because it is a share of that total. - location covers the account's whole location family, so those rows total MORE than an unsegmented read, which covers only the account you asked for. - search_term_group overlaps and omits: a term in two groups appears in both rows, a term in no group in neither. Compare groups with each other, never total them. MEASUREMENT CHANGE ON 8 OCT 2026. `filters.tracking` reports where the requested window sits against it: `state` is "none" (every period uses the current measurement), "all_earlier", or "mixed". When state is not "none", `filters.tracking.caveat` carries a sentence explaining it - QUOTE THAT CAVEAT alongside any figure you report from such a window. Before 8 Oct a search was counted only where a result appeared; from 8 Oct every tracked search is counted, so the denominator grew and rates fell with no change in the market. Adthena changed how it measures; Google changed nothing - never tell a customer that Google changed anything. What is not comparable across `first_clean_period` is anything DIVIDING by the scrape count - frequency and results per search - so do not compute a change, trend or percentage difference in those across that date. A SHARE is comparable: it divides a business's appearances by all businesses' appearances, and the change touched neither. Do not hedge a share trend as a measurement artefact. `first_clean_period` MOVES WITH THE GRAIN - daily 2026-10-08, weekly 2026-10-11, monthly 2026-11-01 - because a weekly or monthly bucket that starts before 8 Oct still contains old-measure days. If you do not pass `time_period` it is auto-resolved from the date range, so asking about a window starting more than ~30 days ago silently gets weekly buckets and the later boundary. Read `filters.time_period` and `filters.tracking` back from the response rather than assuming the grain you expected. Use page_size=0 to get every row rather than a page. See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segment_by details.

get_local_service_ads

Get competitor market share data showing performance in clicks, spend, and impressions. report_type options: - "detail": Per-competitor rows with share metrics. Paginated. - "groups_and_locations": Market share broken down by every search term group and location combination. - "summary": Single overview with your shares, market leader, and top N competitors. Uses top_n instead of pagination. Response fields (detail): competitor, device, ad_type, location_name, estimated_impressions, share_of_clicks, share_of_spend, share_of_impressions, average_position, relevant_search_terms, average_cpc, average_ctr. Response fields (groups_and_locations): competitor, device, ad_type, location_name, search_term_group_name, estimated_impressions, total_impressions, share_of_clicks, share_of_spend, share_of_impressions, average_position. This shape differs from detail: it adds search_term_group_name and total_impressions, and carries NO relevant_search_terms and NO cpc/ctr. Response fields (summary): device, ad_type, location_name, total_competitors, total_estimated_impressions, your_share_of_clicks, your_share_of_spend, your_share_of_impressions, your_average_position, your_relevant_search_terms, your_average_cpc, your_average_ctr, avg_share_of_clicks, median_share_of_clicks, market_leader, market_leader_share_of_clicks, and a nested top_competitors[] list whose entries carry competitor, share_of_clicks, share_of_spend, share_of_impressions, average_position, estimated_impressions, relevant_search_terms, average_cpc, average_ctr. Efficiency metrics: this tool always requests them, so `average_cpc` / `average_ctr` (and `your_average_cpc` / `your_average_ctr` on summary) come back on detail and summary. They are absent from the published OpenAPI schema by design - do not conclude from the docs that they are unavailable. They are still omitted per the usual rule when the underlying spend or click data is missing. Absolute data: accounts entitled to absolute figures additionally receive the share numerators and denominators on detail and groups_and_locations - share_of_clicks_numerator/_denominator, share_of_spend_numerator/_denominator, share_of_impressions_numerator/_denominator. These are also absent from the published schema, and absent entirely for accounts without the entitlement, so treat them as a bonus rather than something to depend on. Entitlement is a property of the account, NOT of the `filtering_options` argument. order_by options vary by report_type: - "detail": share_of_clicks, share_of_spend, estimated_impressions, share_of_impressions, average_position, competitor, relevant_search_terms - "groups_and_locations": share_of_clicks, share_of_spend, estimated_impressions, share_of_impressions, average_position, competitor - "summary": share_of_clicks, share_of_spend Use filtering_options="absolute" for absolute numbers instead of shares. When comparing two periods, use page_size=0 to get all competitors. See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segment_by details.

get_market_share

Get competitor performance trends over time as time series data. Returns time series for the top N competitors (max_number_of_domains, default 10, max 1000), ranked by primary_dimension. primary_dimension options: "share_of_clicks" (default), "share_of_spend", "share_of_impressions", "average_position", "average_cpc", "frequency_share". Response: list of segments, each with competitors and time_series of {date, share_of_clicks, share_of_spend, share_of_impressions, average_position, average_cpc, frequency_share}. Absolute data: accounts entitled to absolute figures additionally receive, on every point, a _numerator and _denominator twin for each share metric (share_of_clicks, share_of_spend, share_of_impressions, frequency_share) plus estimated_impressions and overall_estimated_impressions. These are absent from the published OpenAPI schema by design, so do not conclude from the docs that they are unavailable - but they are also absent entirely for accounts without the entitlement, so check for the keys rather than depending on them. Entitlement is a property of the account, NOT of the `filtering_options` argument. No pagination - returns all data points, ordered by date ascending. See docs://date-rules for date and time_period handling. See docs://data-access for segment_by details.

get_market_trends

Get SERP Tracker rule matches - ads on the search results page that triggered a configured rule. These are *rule matches*, **not legal infringements**. Many legitimate competitor behaviours (e.g. permitted brand-bidding on your terms) trip rules. When summarising to a user, say "rule matches" or "SERP Tracker matches" - never "infringements". SERP Tracker is the in-platform name for what was formerly called the "Infringement Tracker". Adthena scans the SERP every hour for ads that match rules configured for your account (brand misuse, unauthorized resellers, etc.). For trademark-specific detections that feed Google's Auto-Takedown system, use `get_auto_takedown` instead. For the enforcement *outcomes* of trademark takedowns (successful / unsuccessful / pending), use `get_trademark_takedowns`. report_type options: - "matches" (default): Detailed match records. Requires start_date/end_date. Paginated. - "summary": Aggregated stats including total_matches, unique_competitors, top-N competitors by match_count. Requires start_date/end_date. - "rules": SERP Tracker rule configurations for the account. No dates needed. Paginated. Response fields (matches): name (rule name), id, date_time, device, location_name, competitor, search_term, title, description1, description2, click_url, destination_url, display_url, position, evidence_link. `evidence_link` is an opaque, server-generated URL to Adthena's stored capture of the SERP for that match. It has no derivable structure and is only valid exactly as returned - it cannot be reconstructed from the competitor, search term, date, or any other field. The same applies to `click_url`, `destination_url`, and `display_url`, which are captured from the live ad. Surface these links verbatim; a record may omit `evidence_link`, in which case no evidence capture exists for it. Response fields (summary): total_matches, unique_competitors, unique_search_terms, desktop_count, mobile_count, top_competitors (each with competitor + match_count). Response fields (rules): id, name, device, enabled, location_name, email_count. order_by for matches: "name", "search_term", "date_time" (default). order_by for rules: "name". See docs://date-rules for date handling.

get_serp_tracker

Get search term analysis data. report_type options: - "detail": Per-search-term performance data. Paginated. - "detail_summary": Pre-aggregated overview stats. Uses top_n. - "opportunities": Terms competitors bid on but you don't. Paginated. Limited to last 30 days, forces daily time period. Does not support ad_type, segment_by, is_whole_market, or time_period. - "opportunities_summary": Pre-aggregated opportunities stats. Same constraints as opportunities. Uses top_n. Response fields (detail): search_term, device, ad_type, location_name, competitors, top_competitor, estimated_impressions, estimated_clicks, average_position, min_cpc, max_cpc, is_priority, is_ignored. Response fields (opportunities): search_term, device, location_name, competitors, top_competitor, estimated_clicks, total_clicks, average_position, min_cpc, max_cpc, is_priority, is_ignored, is_rejected. There is no ad_type field on this report_type, and no estimated_impressions. order_by options for detail: "search_term", "estimated_impressions", "estimated_clicks", "competitors", "average_position", "top_competitor". order_by options for opportunities: "search_term", "estimated_clicks". See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segment_by details.

get_search_terms

Get Google's trademark auto-takedown enforcement outcomes. Different from get_auto_takedown (the trademark detections) - this shows Google's enforcement outcomes on reported cases. report_type options: - "detail": Individual takedown records. Paginated. - "summary": Aggregated counts and success_rate with top domains. Uses top_n. Response fields (detail): case_id, domain_name, status (successful/unsuccessful/pending), reason, timestamp, company_name, geo_location_code, trademark_details. Response fields (summary): successful_count, unsuccessful_count, pending_count, total_count, success_rate, top_domains. success_rate = successful_count / (successful_count + unsuccessful_count). Pending cases are excluded from the denominator. Null when there are no resolved (non-pending) cases. See docs://date-rules for date handling.

get_trademark_takedowns