Get the performance of the connected ad accounts
paid_insights.insights.get
Returns the paid advertising performance of the organization's connected ad accounts (Google Ads, Meta Ads, TikTok Ads, LinkedIn Ads), read live from each platform on every call: it can take several seconds. period is 7d, 14d or 30d (default; that many complete days ending yesterday, compared with the same number of days right before), month_to_date (this month up to yesterday, compared with the same days of last month) or last_month (compared with the month before); range has the exact dates of both. platforms limits the read to some platforms (google_ads, meta_ads, tiktok_ads, linkedin_ads); without it every connected ad account is read. In the result, platforms has one entry per ad account (a platform can have several) with platform_id, connection_id (platform:account id on the platform), connection_name, currency (the account's ISO code, when the connection recorded it), the period's totals and the previous period's (comparison, null if it could not be read) keyed by the platform's own metric ids (metric_ids names the key of spend, impressions, clicks and conversions on that platform; Google Ads reports spend as cost_micros, already in currency units despite its name), and the period's campaigns with impressions, sorted by name (status active, paused, removed, or unknown when the report does not carry it; ctr and conversion_rate in %, cpc, spend, conversions, cost_per_conversion; amounts in the account's currency); idle_campaigns counts the ones left out for having no impressions (include_idle_campaigns=true lists them too). include_series=true adds a daily series per account with the same KPIs and units as the campaigns (date, spend, impressions, clicks, conversions, ctr in %, cpc). An ad account whose read failed (expired connection, missing permission, the platform's API temporarily down) comes with error and empty totals; the others still return. aggregated: the screen's KPIs across the accounts that answered: total_spend, total_impressions, total_clicks, total_conversions, their % change against the previous period (100 when the previous period was zero; null when both are zero or nothing could be compared) and 7-point sparklines of the period's last 7 days. When the accounts use different currencies, currency_info is present and the aggregated spend is in USD, converted with its rates (1 USD = rate units); a currency missing from rates (all of them when rates is empty: the exchange-rate lookup failed) is added unconverted. With no ad account connected it returns empty platforms and zeroed KPIs, never an error; ad accounts are connected in MB Suite (Settings → Integrations). It counts against the organization's Google Ads external quota (the scarcest provider quota): one unit per live Google Ads request (three per Google Ads account), or one per call when no Google Ads account is read; the platforms filter reads (and spends) less. Requires view access to Paid Insights. With Google Ads, LinkedIn or TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their records are left out of the response (the permissions guide lists what each platform allows).
Instructions for agents
If an ad account comes with error, name it and say why instead of reporting its zeros as real numbers; an expired connection or a missing permission is fixed by reconnecting it in Settings → Integrations. Read each account's KPIs from totals[metric_ids.*] (Google Ads' cost_micros is already in currency units) or from its campaigns and series, which use common names. Do not add spend across accounts with different currencies yourself: use aggregated, which is in USD when currency_info is present.
- Scope
paid_insights:read- Permission
- View the module
- MCP tool
paid_insights_insights_getOn the full surface; on the compact one,mb_execute_operationwithid: "paid_insights.insights.get".
Declared cost: up to 50 reads and 0 writes per call (they count against the daily quota). Touches an external platform (google_ads): it counts against the external operations quota.
Parameters
periodenumqueryoptional7d, 14d or 30d (default): that many complete days ending yesterday, compared with the same number of days right before. month_to_date: from the 1st of this month to yesterday, compared with the same days of last month (on the 1st it is last month). last_month: last month, compared with the month before.
Values: 7d, 14d, 30d, month_to_date, last_month · Default: "30d"
platformsarray<enum>queryoptionalRead only the ad accounts of these platforms (google_ads, meta_ads, tiktok_ads, linkedin_ads). Omit it to read every connected ad account.
Values: google_ads, meta_ads, tiktok_ads, linkedin_ads
include_seriesbooleanqueryoptionalAlso return each account's daily series (date, spend, impressions, clicks, conversions, ctr in %, cpc). Default false: aggregated has 7-day sparklines; ask for the series only to read day by day.
Default: false
include_idle_campaignsbooleanqueryoptionalAlso list the campaigns with no impressions in the period. Default false: they are left out and idle_campaigns says how many.
Default: false
Response
periodenumValues: 7d, 14d, 30d, month_to_date, last_month
rangeobjectThe exact days of the period and of the comparison.
platformsarray<object>One entry per connected ad account read (a platform can have several).
aggregatedobjectcurrency_infoobjectPresent when the accounts use different currencies.
Errors
Example
curl "https://api.mb-suite.com/v1/paid-insights" \
-H "Authorization: Bearer $MB_API_KEY"Try it with your test API key
With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.