PlugsightDocs

Marketing and analytics tools

Search Console, Google Analytics, Google Ads and Microsoft Advertising tools in the developer API, with every argument.

Needs: Google Search Console, Google Analytics, Google Ads or Microsoft Advertising (Pro and Agency). 12 tools.

These tools appear in GET /v1/tools only when the API key's MCP server includes a connection of this kind. Call each one with POST /v1/tools/\<name>, sending its arguments as a JSON object. See Calling tools for the request and response format.

Marketing tools don't take an account from list_accounts. Call list_marketing_accounts for the sites, properties and ad accounts this key reaches, and pass their ids as accounts (leave it out for all). Sites or accounts you've hidden in Plugsight aren't listed and can't be read.

Tool What it does Kind
list_marketing_accounts List marketing accounts Read
list_marketing_fields List marketing data fields Read
get_marketing_data Get marketing data Read
marketing_deep_dive Marketing deep dive Read
search_console_inspect_url Inspect URL in Search Console Read
search_console_sitemaps List sitemaps Read
analytics_realtime Google Analytics 4 realtime Read
analytics_key_events GA4 key events Read
analytics_funnel GA4 funnel Read
analytics_metadata GA4 dimensions and metrics Read
google_ads_query Google Ads query (GAQL) Read
microsoft_ads_campaigns Microsoft Advertising campaigns Read

The example requests fill in only the required arguments, with placeholder values.

list_marketing_accounts

List marketing accounts · Read

Lists the marketing connections this MCP can use and everything they reach: Search Console sites, Google Analytics 4 properties, Google Ads customers (including accounts under a manager/MCC) and Microsoft Advertising (Bing Ads) accounts. Use the returned ids in the other marketing tools. Call this first.

Argument Type Required What it is
service string No Only this service. One of: google_ads, microsoft_ads, search_console, analytics.
search string No Only resources whose name or id contains this text
refresh boolean No Re-discover now instead of using the 15-minute cache. Default false.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/list_marketing_accounts \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

list_marketing_fields

List marketing data fields · Read

Every field get_marketing_data accepts for a connector, as dimensions and metrics with descriptions. Derived metrics (ctr, cpc, cpa, roas, conversion_rate…) are recalculated after combining rows, so they stay correct across accounts.

Argument Type Required What it is
connector string Yes google_ads, microsoft_ads (Microsoft Advertising / Bing Ads), search_console, analytics (GA4) One of: google_ads, microsoft_ads, search_console, analytics.
search string No Only fields whose name or description contains this

Example request:

curl -X POST https://app.plugsight.app/v1/tools/list_marketing_fields \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector": "google_ads"}'

get_marketing_data

Get marketing data · Read

The main analysis tool. Pulls any combination of dimensions and metrics from Google Ads, Microsoft Advertising, Search Console or GA4, for one, several or all connected accounts at once, and returns a compact table with totals. Pick fields from list_marketing_fields. The right report is chosen automatically (e.g. search_term → search-term report, keyword → keyword report). Examples: converting keywords: fields [keyword, match_type, campaign, cost, conversions, cpa, conversion_value, roas] with filter conversions gt 0; wasted spend: [search_term, keyword, cost, clicks, conversions] with conversions eq 0 and cost gt 20; SEO: [query, page, clicks, impressions, ctr, position]. Rows from different accounts are combined unless account_name is a field. data_notes explain any data Google/Microsoft withhold.

Argument Type Required What it is
connector string Yes google_ads, microsoft_ads (Microsoft Advertising / Bing Ads), search_console, analytics (GA4) One of: google_ads, microsoft_ads, search_console, analytics.
fields array of string Yes Dimensions and metrics, in output column order
accounts array of string No Account / customer / property ids or site URLs from list_marketing_accounts. Omit for all
date_preset string No Used when date_from/date_to aren't given. Default last_30d. One of: today, yesterday, last_7d, last_14d, last_28d, last_30d, last_90d, last_180d, last_365d, this_month, last_month, this_year, last_year.
date_from string No YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo")
date_to string No YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo")
filters array of object No All combine with AND. Text matching ignores case. Metric filters apply after combining rows. Default [].
order_by array of object No Default: first metric, descending
limit integer No Rows returned (after sorting) Default 500.
max_rows_per_account integer No Rows fetched per account before combining. Default 100000.
totals boolean No Add a totals row. Default true.
options object No Advanced report options. Default {}.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/get_marketing_data \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector": "google_ads", "fields": []}'

marketing_deep_dive

Marketing deep dive · Read

Ready-made analyses that combine several queries and return findings plus tables:

  • account_overview: every connected platform/account, this period vs previous (spend, conversions, CPA, ROAS, organic clicks, sessions, revenue)
  • wasted_spend (google_ads/microsoft_ads): non-converting search terms and keywords, % of budget wasted, negative-keyword candidates
  • scale_opportunities (ads): campaigns/keywords at or below average CPA that lose impression share to budget or rank
  • search_term_winners (ads): converting search terms not yet added as keywords
  • quality_score_audit (ads): spend by quality score and which component drags low scores down
  • paid_vs_organic (ads + Search Console): paying where you rank top 3, paid winners with weak SEO, organic queries worth a paid test
  • seo_opportunities (Search Console): striking-distance queries, low-CTR snippets, pages losing clicks
  • period_comparison (any connector, needs fields): this period vs previous period or last year, biggest gains and drops Use get_marketing_data to drill into anything a deep dive surfaces.
Argument Type Required What it is
report string Yes Which ready-made analysis to run. One of: account_overview, wasted_spend, scale_opportunities, search_term_winners, quality_score_audit, paid_vs_organic, seo_opportunities, period_comparison.
connector string No Ads reports: google_ads (default) or microsoft_ads. period_comparison: any. One of: google_ads, microsoft_ads, search_console, analytics.
accounts array of string No Account ids for the connector. Omit for all
site_urls array of string No Search Console sites for paid_vs_organic / seo_opportunities. Omit for all
date_preset string No Default last_30d. One of: last_7d, last_14d, last_28d, last_30d, last_90d, last_180d, last_365d, this_month, last_month, this_year, last_year.
date_from string No YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo")
date_to string No YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo")
compare string No Period to compare with. One of: previous_period, previous_year. Default "previous_period".
fields array of string No period_comparison: dimensions + metrics, e.g. [campaign, cost, conversions, cpa]
filters array of object No period_comparison only
min_cost number No Spend threshold for wasted_spend lists. Default 10.
min_conversions number No Conversion threshold for winners / scale reports. Default 1.
min_impressions number No Impression threshold for SEO reports. Default 100.
top integer No Rows per table. Default 25.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/marketing_deep_dive \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"report": "account_overview"}'

search_console_inspect_url

Inspect URL in Search Console · Read

Index status of one URL as Google sees it: coverage, last crawl, canonical, mobile usability, rich results.

Argument Type Required What it is
site_url string Yes Site from list_marketing_accounts that contains the URL
url string Yes Full URL to inspect
language_code string No For translated issue messages, e.g. en-GB
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/search_console_inspect_url \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_url": "…", "url": "…"}'

search_console_sitemaps

List sitemaps · Read

Sitemaps submitted for a Search Console site, with submitted/indexed counts, errors and warnings.

Argument Type Required What it is
site_url string Yes Search Console site from list_marketing_accounts (optional with one site)
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/search_console_sitemaps \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_url": "…"}'

analytics_realtime

Google Analytics 4 realtime · Read

Activity in the last 30 minutes, e.g. activeUsers by country, unifiedScreenName or eventName (GA4 API names).

Argument Type Required What it is
property_id string Yes GA4 property id from list_marketing_accounts (optional with one property)
metrics array of string No GA4 realtime metrics. Default ["activeUsers"].
dimensions array of string No GA4 realtime dimensions. Default [].
limit integer No Most results to return. Default 50.
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/analytics_realtime \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "…"}'

analytics_key_events

GA4 key events · Read

The events a GA4 property counts as key events (conversions), with how many happened and the key event rate in a period. Use it to answer 'what counts as a conversion here' and 'which conversions are happening'. For breakdowns by channel or page, use get_marketing_data with conversions.

Argument Type Required What it is
property_id string Yes GA4 property id from list_marketing_accounts (optional with one property)
start_date string No YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "28daysAgo".
end_date string No YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "yesterday".
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/analytics_key_events \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "…"}'

analytics_funnel

GA4 funnel · Read

Builds a funnel from 2–10 steps and shows how many users reach each step, the completion rate and where they drop off. Each step is an event (e.g. view_item, add_to_cart, begin_checkout, purchase) or a page (page view whose URL contains text). Closed funnels (default) count users who start at step 1; open funnels let users enter at any step. Optionally break down by a dimension such as deviceCategory or sessionDefaultChannelGroup.

Argument Type Required What it is
property_id string Yes GA4 property id from list_marketing_accounts (optional with one property)
steps array of object Yes Funnel steps, in order: each a name and an event
open_funnel boolean No true: people can enter at any step. Default false.
breakdown string No GA4 dimension, e.g. deviceCategory
start_date string No YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "28daysAgo".
end_date string No YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "yesterday".
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/analytics_funnel \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "…", "steps": []}'

analytics_metadata

GA4 dimensions and metrics · Read

All dimensions and metrics available for a GA4 property, including its custom definitions. Any of these work in get_marketing_data.

Argument Type Required What it is
property_id string Yes GA4 property id from list_marketing_accounts (optional with one property)
search string No Only fields whose name or description contains this
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/analytics_metadata \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_id": "…"}'

Google Ads query (GAQL) · Read

Runs any read-only Google Ads Query Language SELECT against one customer, for anything get_marketing_data doesn't cover. Rows come back flattened ("campaign.name", "metrics.clicks"). cost_micros ÷ 1,000,000 = account currency. Manager accounts can't report metrics; query their clients.

Argument Type Required What it is
customer_id string Yes Customer id from list_marketing_accounts (dashes optional)
query string Yes GAQL SELECT statement
limit integer No Most results to return. Default 500.
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/google_ads_query \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "…", "query": "…"}'

microsoft_ads_campaigns

Microsoft Advertising campaigns · Read

Campaign settings in a Microsoft Advertising account: status, type, budget and bidding strategy.

Argument Type Required What it is
account_id string Yes Account id from list_marketing_accounts (optional with one account)
connection string No Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically.

Example request:

curl -X POST https://app.plugsight.app/v1/tools/microsoft_ads_campaigns \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "…"}'