Adthena

Get AI Ads Intelligence data: how often the brand and competitors appear in paid LLM ad placements (ChatGPT and Google AI). This is a separate surface from get_llm_performance — it tracks PAID AD placements inside LLM responses, not organic citations. Engines are "chatgpt" and "googleai" (NOT "perplexity"). 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. IMPORTANT: start_date must be within the last 30 days. end_date must not be later than yesterday (today's data is not yet available). Dates in YYYY-MM-DD format. Soft-delete behaviour: includes any AI Ads prompt that was active during any part of the requested window. A prompt deleted mid-window contributes data for the days it was alive — so historical metrics can reference prompts no longer returned by get_llm_ad_prompts(). The `prompt_group` filter follows the same active-during-window rule. The `prompt` filter is different: it matches the underlying scrape data directly, so a fully-historic prompt name still matches as long as scrape rows exist for it. report_type options: - "performance_trends" (default): one segment per (engine, location) bucket with period-level summary metrics (ad_presence_rate, prompts_with_ads, total_prompts, competitors_detected, top_competitor, top_competitor_detection_rate) and a daily time_series (date, ad_presence_rate, prompts_with_ads, competitors_detected). Unpaginated. - "advertiser_share_trends": one segment per (engine, location) containing a competitors list — the brand row first, then top competitors by detection count (cap via max_number_of_domains, default 5). Each entry carries a period share_of_ads and a daily time_series (date, share_of_ads). Unpaginated. - "prompts_analysis": one row per prompt with brand vs competitor rates (your_ads_detection_rate, top_competitor_rate, avg_competitor_detection_rate, you_vs_top_competitor_rate), the competitors list, competitors_count, and is_greenfield flag. Paginated. prompt_status (prompts_analysis only): "with_brand_ads" = prompts where the brand has ads; "gap" = prompts where competitors have ads but the brand does not; "all" = both (default). segment_by=["engine"] splits the trend results per LLM engine; empty default aggregates engines into a single comma-joined label like "chatgpt, googleai". Ignored for prompts_analysis. max_number_of_domains (advertiser_share_trends only): 1-100, default 5. The brand row is always returned in addition to these competitors. Sorting (prompts_analysis only): order_by one of "prompt", "your_ads_detection_rate" (default), "top_competitor_rate", "avg_competitor_detection_rate", "competitors_count". order_direction defaults to "desc". Default page_size is 0 (all results). AI Ads Intelligence volumes are small; pass a specific page_size only if you need smaller pages. DATA INTERPRETATION — how to read the response (fields, omissions, zero-fill): - All rate fields (*_rate, share_of_ads) are in [0, 1]. - The API NEVER returns JSON `null`. Undefined values are OMITTED FROM THE RESPONSE (the key is absent), not serialized as `null`. To detect "undefined", check for key absence — `field is None in JS/Python after parsing` because the key doesn't exist, not because it was explicitly null. - `ad_presence_rate` (both period-level and per-day in time_series) is ALWAYS PRESENT and numeric — the DAO zero-fills buckets with no data and substitutes 0 for any undefined value. A `0` is therefore AMBIGUOUS: it can mean "no scrapes occurred" OR "scrapes occurred but the brand was not detected". Use the corresponding `total_prompts` field at the same level to disambiguate (never use the period-level value to interpret a daily value, or vice versa): - PERIOD level: each segment exposes a `total_prompts`. `total_prompts > 0` ⇒ scrapes occurred during the period ⇒ `ad_presence_rate = 0` is a real "brand absent across the period" signal. `total_prompts = 0` ⇒ no scrapes occurred in the period ⇒ the rate carries no signal; do not recommend action. - PER-DAY level: each `time_series` point also exposes a `total_prompts` (count of distinct prompts scraped on that day). Same rule: `total_prompts > 0` ⇒ scrapes occurred that day ⇒ `ad_presence_rate = 0` means the brand was absent that day; `total_prompts = 0` ⇒ no scrapes that day, the rate carries no signal. - In `prompts_analysis` this ambiguity does NOT exist — every returned row has scrapes > 0 (SQL HAVING filter), so an absent `your_ads_detection_rate` is a definitive "brand absent" signal. - Period-level rate fields that CAN be omitted (the key is absent). Each carries a specific presence/absence signal — absence tells you which entity is missing from the data, not "we couldn't compute". For all of these, the rate would have been 0 had it been emitted: - `your_ads_detection_rate` (prompts_analysis): absent ↔ the brand had zero detections on that prompt. - `top_competitor_rate`, `avg_competitor_detection_rate` (prompts_analysis), `top_competitor_detection_rate` (performance_trends): absent ↔ no competitors were detected. - `you_vs_top_competitor_rate` (prompts_analysis): absent ↔ either the brand or the competitors are absent (or both). - `share_of_ads` (period and daily) is always present — advertisers with zero detections in the period don't appear in the response at all, including the brand. If a brand row is missing from `advertiser_share_trends`, the brand had no detections in that bucket. - `top_competitor` key is OMITTED when no competitors were detected in that bucket / on that prompt. Treat absence as "uncontested", not "missing data". - In prompts_analysis: a row with `your_ads_detection_rate` absent and `competitors_count > 0` is a GAP prompt. A row with `top_competitor` absent and `your_ads_detection_rate` present is a GREENFIELD prompt (also signalled explicitly via `is_greenfield: true`). - `is_greenfield` is always present (boolean). True when the brand has detections AND no competitors were detected. - `competitors` entries may have `domain: ""` — the source data has no domain for that advertiser. The name is authoritative; do not infer "missing data". - Zero-fill is guaranteed: every requested (engine, location) bucket always appears, and every day in [start_date, end_date] appears in each time_series. An empty time_series or a date gap would be a bug. - `engine` field on segments: a single engine name when segment_by=["engine"]; otherwise a sorted comma-joined label (e.g. "chatgpt, googleai") representing the aggregated bucket. - No prior-period deltas are computed server-side. To compare two periods, call this tool twice with adjacent date ranges and compute deltas client-side. These endpoints only support prompt-based filtering — no device, ad_type, search_term, competitor, competitor_group, or adwords_campaign filters. Use get_llm_prompts() to discover available prompts and prompt groups for filtering. See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segmentation. See docs://concepts for metric definitions (Ad Presence Rate, Share of Ads, Greenfield/Gap prompts). See docs://workflows section "AI Ads Intelligence Visibility Analysis" for a multi-step analysis pattern.

get_ai_ads_intelligence

Get AI Overview appearance data and frequency metrics. IMPORTANT: start_date must be 2025-07-31 or later. report_type options: - "overview": Time series of AI Overview appearance frequency. No pagination. - "search_terms": Per-term AI Overview data. Paginated. Response fields (overview): date, appearances, frequency, overall_frequency, intent category shares, word count buckets. Premium accounts also get ad position data. Response fields (search_terms): search_term, device, impressions, frequency, intent categories, word count. term_type for search_terms: ["wmv"] (default) or ["premium"] (premium-enabled accounts only). order_by for search_terms: "search_term", "impressions", "frequency". No competitor, ad_type, is_whole_market, or adwords_campaign filters on this endpoint. See docs://date-rules for date and time_period handling. See docs://data-access for segment_by details.

get_ai_overview

Get AI Overview citation analysis: sentiment, themes, and competitor citations. Premium-only. start_date must be within the last 30 days. Dates in YYYY-MM-DD format. report_type options: - "content": Citation frequency, sentiment breakdown (favourable/unfavourable/neutral/comparative/inconclusive), theme breakdown (how_to/comparison/problem_solve/review/faq/news), top 5 cited domains by position, and daily citation frequency time series. No pagination. - "competitors": Top cited domains with overall citation share and daily time series per domain. No pagination. Use max_number_of_domains to control how many domains are returned (default 10). max_number_of_domains only applies to report_type="competitors" (1-1000, default 10). No competitor, location, or term_type filters on these endpoints. See docs://data-access for segment_by and filtering details.

get_ai_overview_content

Get AI Overview impact on CTR and CPC with frequency breakdown. Premium-only. start_date must be within the last 30 days. Dates in YYYY-MM-DD format. report_type options: - "impact": Aggregate CTR/CPC with vs without AI Overview, per-frequency-bucket breakdown (CTR/CPC by AIO frequency), and daily time series. No pagination. - "search_terms": Paginated list of search terms with their frequency bucket, AIO frequency, estimated AIO impressions, and search volume. Use bucket_label to filter by specific frequency buckets. bucket_label values (for search_terms): "0", ">0-25", ">25-50", ">50-75", ">75-<100", "100". Omit for all buckets. For "impact": device and segment_by are supported. For "search_terms": device is fixed to both desktop+mobile (not selectable). order_by defaults to "search_volume". No competitor, location, or term_type filters on these endpoints. See docs://data-access for segment_by and filtering details.

get_ai_overview_impact

Get account configuration data: locations, search term groups, and group metrics. Call "locations" or "search_term_groups" first to discover values for use as filters in other tools. setting_type options: - "locations": All locations in the account hierarchy. No extra params needed. - "search_term_groups": Group hierarchy with metadata. Paginated. - "search_term_groups_metrics": Groups with performance metrics. Requires start_date, end_date, device. Paginated. Response fields (search_term_groups): group_name, group_type, created_at, created_by, modified_at, modified_by, search_term_count. Response fields (search_term_groups_metrics): group_name, group_type, estimated_impressions, share_of_clicks, share_of_spend, average_position, competitor_count. order_by for groups: "group_name", "group_type", "created_at", "created_by", "modified_at", "modified_by". order_by for metrics: "total_estimated_clicks", "group_name", "total_estimated_impressions", "total_estimated_spend", "avg_position", "competitor_count". See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segment_by details.

get_account_settings

Get the most frequent ad copies or product listing ads. ad_format options: - "text" (default): Top text ads. Use ad_type to control which: ["textad"], ["organic"], or both. - "pla": Top product listing ads. Requires PLA enabled. ad_type not applicable. Response fields (text): ad_id, ad_type, device, location_name, competitor, title, display_text, description1, description2, frequency, first_seen, last_seen, estimated_impressions, search_terms, best_position, average_position. Response fields (pla): ad_id, device, location_name, competitor, title, display_text, frequency, first_seen, last_seen, estimated_impressions, search_terms, price, old_price, price_numeric, old_price_numeric, rating, shopping_tag, badge, image, comparison_shopping_services (CSS — Comparison Shopping Services — provider that placed the ad, e.g. "Google Shopping" or a third-party CSS partner; may be null), return_policy. order_by options for text: "frequency", "estimated_impressions" (default). order_by options for pla: "frequency", "estimated_impressions" (default), "price". Use ad_text/excluded_ad_text for text search. Use is_new=true for ads first seen in last 7 days, is_current=true for last seen in last 7 days (text only). Data is always segmented by device and ad_type. See docs://date-rules for date and time_period handling.

get_ads

Get ad hijacking detection data. Workflow: Call "configurations" first to get IDs, then use configuration_id with "incidents" or "summary". report_type options: - "configurations" (default): Hijacking rule configs. Only needs account_id. Paginated. - "incidents": Detailed hijacking records. Requires configuration_id, start_date, end_date. Paginated. - "summary": Aggregated stats with top hijackers. Requires configuration_id, start_date, end_date. Response fields (configurations): name, id, created/modified dates, enabled status. Response fields (incidents): one object per hijacking instance - geo_code, hijacker_id, ad_url, final_url, date, domain, device, search_term, utm_params, evidence_link, redirect_count, and a nested redirects[] chain. Each redirects[] hop has order_num, redirect_url, affiliate_network_name, affiliate_id, sub_id, date. Results are sorted by date, newest first by default; pass order_direction to override. `evidence_link` is an opaque, server-generated URL to Adthena's stored capture of the hijacking incident. It has no derivable structure and is only valid exactly as returned — it cannot be reconstructed from the domain, search term, date, or any other field. The same applies to the captured `ad_url`, `final_url`, and each `redirects[].redirect_url`. Surface these links verbatim; a record may omit `evidence_link`, in which case no evidence capture exists for it. Response fields (summary): total_incidents, unique_hijackers, device_breakdown, top_hijackers. Use affiliate_text to search affiliate_id/sub_id. Use network_name to filter by affiliate_network_name. See docs://date-rules for date handling.

get_ad_hijacking

Get Adthena-detected trademark cases — the inputs to Google's Auto-Takedown enforcement system. These are *detections*, not enforcement outcomes. After a user reports a detection from the Adthena app, the downstream outcome (successful / unsuccessful / pending) is returned by `get_trademark_takedowns` — a separate tool. Detection → report → enforcement outcome. For the general SERP Tracker rule family (non-trademark rule matches), use `get_serp_tracker` instead. report_type options: - "matches" (default): Detailed detection 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": Auto-Takedown 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 detection. 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_auto_takedown

Get Brand Activator data showing automated bid management activity and savings. CRITICAL: Savings UP = fewer competitors (good). Savings DOWN = more competitors (bad). Do NOT invert this. See docs://workflows § Brand Activator Analysis for full interpretation rules and common mistakes to avoid. IMPORTANT: Only search_term filtering available (no competitor/group/location filters). report_type options: - "activity_log": Activity records. Paginated. LIMITED TO LAST 60 DAYS. - "daily_savings": Daily savings per search term. Paginated. No date restriction. - "daily_savings_summary": Aggregated savings overview. Uses top_n. No date restriction. Response fields (activity_log): search_term, action, reason, domains, timestamp. Response fields (daily_savings): search_term, date, currency, savings, in_negative_list, competitor_count. Response fields (daily_savings_summary): total_savings, currency, total_days, avg_daily_savings, max_daily_savings, total_search_terms, avg_competitor_count, avg_time_in_negative_list_pct, top_search_terms. See docs://workflows § Brand Activator Analysis for interpretation rules.

get_brand_activator

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. See docs://date-rules for date and time_period handling. See docs://data-access for pagination and segment_by details.

get_competitor_overlap