Get ads selection analytics
get_ads_analyticsGet the bounded analytics overview for the current Meta /ads selection: total and display_total plus statuses, countries, AI categories, landing domains, advertisers and webmasters. This is a Pro-or-higher paid surface; every delivered breakdown row costs 1 MCP credit, pending/error responses refund the reservation. The default is 10 rows per section and the absolute maximum is 20; results are flattened in data with a dimension field and include section readiness/truncation metadata. Totals are nullable: null with pending/unavailable status is NOT zero; exact zero is numeric 0 with an exact status. Only the status section removes its own filter; every other section uses the full filtered universe. No pagination, sorting, source, scheduler, force-scrape, TikTok, raw SQL or storage coordinates are accepted. Auto-applied subscription categories are reported in auto_applied_verticals and scope_note. Re-issue the identical call after retry_after_seconds when pending; do not blindly retry paid calls. PRICING: price × number of filters set (min 1), on paid plans ×1 after 500 MCP credits/month; one-time consent via accept_pricing_terms; before calling, get the maximum debit from estimate_cost (free) and tell the user.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "get_ads_analytics"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | free-text filter, at most 100 UTF-8 bytes | |
| saved | No | saved scope: all | |
| dedupe | No | collapse duplicate creative rows | |
| channel | No | messaging shortcut: whatsapp or telegram | |
| country | No | legacy single ISO-2 include country; prefer countries | |
| date_to | No | Facebook launch upper bound YYYY-MM-DD | |
| page_id | No | Facebook page id or bounded facebook.com page URL | |
| pixel_id | No | bounded Facebook pixel identifier | |
| countries | No | unique uppercase ISO-2 include countries, maximum 200 | |
| date_from | No | Facebook launch lower bound YYYY-MM-DD | |
| folder_id | No | non-zero favorite folder UUID | |
| languages | No | target language slugs, maximum 50 | |
| platforms | No | Meta publisher placements, maximum 6 | |
| search_in | No | query scope: all, title, advertiser or text | |
| categories | No | AI category slugs, maximum 50 | |
| cta_buttons | No | CTA labels, maximum 50 | |
| hub_domains | No | normalized destination hostnames, maximum 50 | |
| media_types | No | media types: image or video | |
| parsing_geo | No | one uppercase ISO-2 parser GEO | |
| resolved_ip | No | resolved IPv4/IPv6 address | |
| search_term | No | historical search term, at most 100 UTF-8 bytes | |
| domain_zones | No | lowercase landing TLD/zone labels, maximum 50 | |
| hub_category | No | closed top-level hub category | |
| status_today | No | current status: active, inactive or vanished | |
| webmaster_id | No | non-zero webmaster UUID | |
| advertiser_id | No | non-zero advertiser UUID | |
| country_match | No | country semantics: any or only | |
| first_seen_to | No | Spytrend discovery upper bound YYYY-MM-DD | |
| max_countries | No | maximum additional/total GEOs, 0 disables, maximum 200 | |
| ai_subcategory | No | taxonomy-valid AI subcategory slugs | |
| days_active_to | No | non-negative active-days upper bound; null omits the filter, 0 is meaningful | |
| favorites_only | No | restrict to the MCP credit-derived user's favorite webmaster scope | |
| impressions_to | No | non-negative impressions bucket upper bound | |
| landing_domain | No | normalized landing hostname | |
| max_page_likes | No | non-negative page-like upper bound; null omits the filter, 0 is meaningful | |
| media_count_to | No | non-negative media-count upper bound | |
| min_page_likes | No | non-negative page-like lower bound | |
| platforms_mode | No | placement semantics: any or all | |
| first_seen_from | No | Spytrend discovery lower bound YYYY-MM-DD | |
| min_days_active | No | non-negative active-days lower bound | |
| ai_enriched_only | No | only AI-enriched ads | |
| creative_formats | No | creative formats: video, carousel, single or dynamic | |
| impressions_from | No | non-negative impressions bucket lower bound | |
| media_count_from | No | non-negative media-count lower bound | |
| ai_confidence_min | No | minimum AI confidence: low, middle or high | |
| contains_in_links | No | tracking-link fragment, at most 255 UTF-8 bytes | |
| fan_page_categories | No | validated fan-page category groups | |
| landing_domain_exact | No | restrict landing domain to exact hostname | |
| max_items_per_section | No | rows per breakdown section, default 10, maximum 20 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| win | No | ||
| data | No | ||
| tier | No | ||
| error | No | Present only when isError is true: machine-readable failure. The human explanation stays in content. | |
| total | No | ||
| params | No | Request parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason. | |
| domains | No | ||
| pending | No | ||
| statuses | No | ||
| countries | No | ||
| ai_labeled | No | ||
| from_cache | No | ||
| scope_note | No | ||
| webmasters | No | ||
| addon_hints | No | Add-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about. | |
| advertisers | No | ||
| computed_at | No | ||
| total_status | No | ||
| ai_categories | No | ||
| display_total | No | ||
| result_status | No | ||
| sections_ready | No | ||
| sections_total | No | ||
| creative_families | No | ||
| display_total_basis | No | ||
| retry_after_seconds | No | ||
| display_total_status | No | ||
| auto_applied_verticals | No |