# 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, Microsoft Advertising, Meta Ads, LinkedIn Ads or TikTok Ads (coming soon) (Pro and Agency; Free can try 1 connection and 25 calls a month). 15 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](https://docs.plugsight.app/developers/calling-tools.md) 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) | List marketing accounts | Read |
| [`list_marketing_fields`](#list_marketing_fields) | List marketing data fields | Read |
| [`get_marketing_data`](#get_marketing_data) | Get marketing data | Read |
| [`marketing_deep_dive`](#marketing_deep_dive) | Marketing deep dive | Read |
| [`search_console_inspect_url`](#search_console_inspect_url) | Inspect URL in Search Console | Read |
| [`search_console_sitemaps`](#search_console_sitemaps) | List sitemaps | Read |
| [`analytics_realtime`](#analytics_realtime) | Google Analytics 4 realtime | Read |
| [`analytics_key_events`](#analytics_key_events) | GA4 key events | Read |
| [`analytics_funnel`](#analytics_funnel) | GA4 funnel | Read |
| [`analytics_metadata`](#analytics_metadata) | GA4 dimensions and metrics | Read |
| [`google_ads_query`](#google_ads_query) | Google Ads query (GAQL) | Read |
| [`microsoft_ads_campaigns`](#microsoft_ads_campaigns) | Microsoft Advertising campaigns | Read |
| [`meta_ads_campaigns`](#meta_ads_campaigns) | Meta Ads campaigns | Read |
| [`linkedin_ads_campaigns`](#linkedin_ads_campaigns) | LinkedIn Ads campaigns | Read |
| [`tiktok_ads_campaigns`](#tiktok_ads_campaigns) | TikTok Ads 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), Microsoft Advertising (Bing Ads) accounts, Meta (Facebook and Instagram) ad accounts, LinkedIn ad accounts and TikTok advertisers (ad 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`, `meta_ads`, `linkedin_ads`, `tiktok_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:

```bash
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), meta_ads (Facebook and Instagram ads), linkedin_ads, tiktok_ads, search_console, analytics (GA4) One of: `google_ads`, `microsoft_ads`, `meta_ads`, `linkedin_ads`, `tiktok_ads`, `search_console`, `analytics`. |
| `search` | string | No | Only fields whose name or description contains this |

Example request:

```bash
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, Meta Ads, LinkedIn Ads, TikTok Ads, 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. Totals use the platform's own figures where it gives them (Search Console, GA4), so they can exceed the sum of rows. Meta Ads: campaign → campaign level, ad_set / ad → finer levels; conversions are purchases unless options.conversion_action names another action. LinkedIn Ads: campaign_group, campaign and ad (creative) levels; conversions are website conversions and leads are Lead Gen Form leads. TikTok Ads: campaign / ad_group / ad set the level; conversions are TikTok's Conversions column and conversion_value is website purchase value; any TikTok report metric is tiktok:\<metric> (rates such as tiktok:ctr are null where rows are combined; prefer the shared ratios). data_notes explain any data Google, Microsoft, Meta or TikTok withhold; partial is true when an account stopped at a row limit (partial_reason says what is incomplete); account_errors lists accounts that couldn't be read.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `connector` | string | Yes | google_ads, microsoft_ads (Microsoft Advertising / Bing Ads), meta_ads (Facebook and Instagram ads), linkedin_ads, tiktok_ads, search_console, analytics (GA4) One of: `google_ads`, `microsoft_ads`, `meta_ads`, `linkedin_ads`, `tiktok_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:

```bash
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 (Google Ads, Microsoft Advertising, Meta Ads, LinkedIn Ads, TikTok Ads, Search Console, GA4), 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`, `meta_ads`, `linkedin_ads`, `tiktok_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`. |
| `conversion_action` | string | No | Meta Ads only: the action type counted as conversions, e.g. lead or complete_registration. Default: purchases |

Example request:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

**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:

```bash
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:

```bash
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": "…"}'
```

## meta_ads_campaigns

**Meta Ads campaigns** · Read

Campaign settings in a Meta (Facebook and Instagram) ad account: status, objective, daily or lifetime budget (in the account's currency) and bid strategy. For results, use get_marketing_data with connector meta_ads.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `account_id` | string | Yes | Ad account id from `list_marketing_accounts` (with or without `act_`) |
| `connection` | string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |

Example request:

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

## linkedin_ads_campaigns

**LinkedIn Ads campaigns** · Read

Campaign settings in a LinkedIn ad account: status, type, objective, campaign group, daily and total budget (in the account's currency), bid and schedule. For results, use get_marketing_data with connector linkedin_ads.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `account_id` | string | Yes | Ad account id from `list_marketing_accounts` |
| `connection` | string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |

Example request:

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

## tiktok_ads_campaigns

**TikTok Ads campaigns** · Read

Campaign settings in a TikTok ad account (advertiser): status, delivery status, objective and budget (daily or total, in the account's currency). For results, use get_marketing_data with connector tiktok_ads.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `account_id` | string | Yes | Advertiser id from `list_marketing_accounts` |
| `connection` | string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |

Example request:

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

## Related articles

- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Authentication](https://docs.plugsight.app/developers/authentication.md)

---

Web version: https://docs.plugsight.app/developers/marketing-tools
