List the Meta Ads campaigns of a connected account
ads_visualizer.meta_ads.campaigns.list
ReadIdempotentSince 2026-11-01
Lists the campaigns of a Meta Ads account connected to the organization: account_id is the ad account id from ads_visualizer.accounts.list (act_ prefix optional). Only enabled and paused campaigns exist here (removed, archived or deleted ones never come); filter with status (enabled, paused, all by default) and search (part of the name or the exact id). Each campaign has id, name, status, state (the Delivery column of the ads managers: active, paused, finished or scheduled), objective (OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC…), start_at/end_at (epoch ms; end_at null = no end date) and delivery_state, derived from those dates when the request runs. It does not return metrics: use ads_visualizer.meta_ads.metrics.get or ads_visualizer.meta_ads.delivery.get. Sorted by name. Paginated by cursor (limit up to 200; follow next_cursor while has_more is true). Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Instructions for agents
Report state as the campaign's status: an enabled campaign past its end date reads finished, and paused wins over everything.
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_campaigns_listOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.campaigns.list".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The Meta Ads account: the Meta ad account id, with or without the act_ prefix. It must be connected to the organization (ads_visualizer.accounts.list).
statusenumqueryoptional
enabled (or active, the same), paused or all (both; the default). Removed, archived and deleted items never come.
Values: all, enabled, paused, active · Default: "all"
searchstringqueryoptional
Part of the name (case-insensitive) or the exact id.
limitintegerqueryoptional
Page size, 1 to 200 (default 50).
Default: 50
cursorstringqueryoptional
next_cursor of the previous page, with the same filters.
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.
Returns how a Meta Ads campaign of an account connected to the organization is set up (cached for 5 minutes): buying_type (AUCTION or RESERVED), special_ad_categories, optimization_goal (the campaign objective), bid_strategy and account_id. campaign_id is the id from ads_visualizer.meta_ads.campaigns.list, and it must be a campaign of that account (404 ad_campaign_not_found otherwise). It does not return metrics or budget pacing: use dashboards.data.query or ads_visualizer.meta_ads.metrics.get. account_id is the ad account id from ads_visualizer.accounts.list (act_ prefix optional). Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_campaigns_getOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.campaigns.get".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The ad account, as ads_visualizer.accounts.list gives it (it must be connected to the organization).
campaign_idstringpathrequired
The campaign (id from the campaigns.list operation of the same platform).
enabled, paused, archived, removed or draft, the vocabulary of the lists (another platform state comes in lowercase); platform_status has the platform's own value.
platform_statusstring
The status as the platform names it (ENABLED, CAMPAIGN_STATUS_DISABLE…).
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.
Returns how an ad set of a Meta Ads account connected to the organization is set up (cached for 5 minutes): optimization_goal, billing_event, bid_amount (in the account's currency), targeting (age_min, age_max, genders, geo_locations countries, interests and custom_audiences by name), placements (automatic, or platform:position), start_time/end_time and account_id. ad_group_id is the id from ads_visualizer.meta_ads.ad_groups.list, and it must be an ad set of that account (404 ad_group_not_found otherwise). account_id is the ad account id from ads_visualizer.accounts.list (act_ prefix optional). Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_ad_groups_getOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.ad_groups.get".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The ad account, as ads_visualizer.accounts.list gives it (it must be connected to the organization).
ad_group_idstringpathrequired
The ad group or ad set (id from the ad_groups.list operation of the same platform).
Response
platformenum
Values: google_ads, meta_ads, tiktok_ads
ad_group_typestring
bidding_strategystring
cpc_bid_microsnumber
target_cpa_microsnumber
effective_target_cpa_microsnumber
effective_target_roasnumber
ad_rotation_modestring
optimization_goalstring
billing_eventstring
bid_amountnumber
targetingobject
placementsarray<string>
start_timestring
end_timestring
bid_typestring
bidnumber
locationsarray<string>
languagesarray<string>
genderstring
age_groupsarray<string>
scheduleobject
statusstring
enabled, paused, archived, removed or draft, the vocabulary of the lists (another platform state comes in lowercase); platform_status has the platform's own value.
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.
Lists the ad sets of a Meta Ads account connected to the organization: those of one campaign (campaign_id) or of the whole account. Meta's ad sets are the ad groups of the Ads Visualizer: their id goes as ad_group_id in the ads and metrics operations. Filter with status (enabled, paused, all by default) and search (part of the name or the exact id). Each ad set has id, name, status, campaign_id, campaign_name, start_at/end_at (epoch ms; end_at null = no end date), delivery_state and state. Sorted by campaign and name. account_id: the ad account id from ads_visualizer.accounts.list (act_ prefix optional). Paginated by cursor (limit up to 200; follow next_cursor while has_more is true). Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_ad_groups_listOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.ad_groups.list".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The Meta Ads account: the Meta ad account id, with or without the act_ prefix. It must be connected to the organization (ads_visualizer.accounts.list).
statusenumqueryoptional
enabled (or active, the same), paused or all (both; the default). Removed, archived and deleted items never come.
Values: all, enabled, paused, active · Default: "all"
searchstringqueryoptional
Part of the name (case-insensitive) or the exact id.
limitintegerqueryoptional
Page size, 1 to 200 (default 50).
Default: 50
cursorstringqueryoptional
next_cursor of the previous page, with the same filters.
campaign_idstringqueryoptional
Only the groups of this campaign. Default: every group of the account.
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.
List the ads of a Meta Ads ad set with their creative
ads_visualizer.meta_ads.ads.list
ReadIdempotentSince 2026-11-01
Lists the ads of one ad set of a Meta Ads account connected to the organization: ad_group_id is the ad set id from ads_visualizer.meta_ads.ad_groups.list. preview (kind meta) carries the creative's fallback: headline, body, image_url, video_thumbnail_url, cta_type, link_url and video_id. The rendered placement previews of the screen (feed, story, reel) are not available through the API. Each ad has id, name, status, type, final_url and its campaign and ad set ids and names. At most 200 ads per ad set; filter with status and search; sorted by name. account_id: the ad account id from ads_visualizer.accounts.list (act_ prefix optional). Paginated by cursor (limit up to 200; follow next_cursor while has_more is true). Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_ads_listOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.ads.list".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The Meta Ads account: the Meta ad account id, with or without the act_ prefix. It must be connected to the organization (ads_visualizer.accounts.list).
ad_group_idstringpathrequired
The ad set (id from ads_visualizer.meta_ads.ad_groups.list).
statusenumqueryoptional
enabled (or active, the same), paused or all (both; the default). Removed, archived and deleted items never come.
Values: all, enabled, paused, active · Default: "all"
searchstringqueryoptional
Part of the name (case-insensitive) or the exact id.
limitintegerqueryoptional
Page size, 1 to 200 (default 50).
Default: 50
cursorstringqueryoptional
next_cursor of the previous page, with the same filters.
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.
Get the performance of each ad of a Meta Ads ad set
ads_visualizer.meta_ads.metrics.get
ReadIdempotentSince 2026-11-01
Returns the performance of each ad of one ad set of a Meta Ads account connected to the organization: impressions, reach, frequency, clicks, ctr (in %), cost, cpc and cpm (in the account's currency, returned in currency), conversions (Meta's conversions_total, without double counting), cost_per_conversion, purchase_roas and, when there are purchases, orders, revenue, aov, roas and transaction_rate. Sorted by cost, highest first. Range: start_date and end_date (YYYY-MM-DD, together, at most 400 days) or period 7d, 14d or 30d (default 30d), complete days ending yesterday in the organization's reporting time zone; the response has the exact dates. Ads without impressions in the range are left out (an empty data means it did not deliver). account_id: the ad account id from ads_visualizer.accounts.list (act_ prefix optional). Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Instructions for agents
Costs are in the account's currency (the currency field): name it. An ad missing from data had no impressions in the range.
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_metrics_getOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.metrics.get".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The Meta Ads account: the Meta ad account id, with or without the act_ prefix. It must be connected to the organization (ads_visualizer.accounts.list).
ad_group_idstringpathrequired
The ad set (id from ads_visualizer.meta_ads.ad_groups.list).
periodenumqueryoptional
7d, 14d or 30d (default): that many complete days ending yesterday. Ignored when start_date and end_date come.
Values: 7d, 14d, 30d · Default: "30d"
start_datestringqueryoptional
First day of the range (YYYY-MM-DD, in the account's time zone). Send it with end_date.
end_datestringqueryoptional
Last day of the range (YYYY-MM-DD, included). At most 400 days after start_date.
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.
Get the impressions of the last 7 days of each Meta Ads campaign
ads_visualizer.meta_ads.delivery.get
ReadIdempotentSince 2026-11-01
Returns the impressions of the last 7 days of each campaign of a Meta Ads account connected to the organization that delivered in that window (campaigns with no impressions are left out), in one request: account_id is the ad account id from ads_visualizer.accounts.list (act_ prefix optional). It is the "only delivering" filter of the ads managers: a campaign can be enabled and within its dates and still not deliver (paused groups, no budget, rejected ads). The window is Meta Ads's own last 7 days. Sorted by impressions, highest first. Read live from Meta Ads (the same data as the Ads Visualizer screen, cached for 5 minutes): it can take a few seconds and counts one unit of the organization's external quota for Meta Ads. Requires view access to the Ads Visualizer. Errors: 404 external_account_not_linked (the account is not connected to this organization); 409 integration_not_connected, integration_reconnect_required (reconnect it in Settings → Integrations; details.reason says why) or external_rejected (details.provider_code and details.provider_message have the platform's own code and words); 429 external_rate_limited and 503 external_unavailable (retry after Retry-After).
Scope
ads_visualizer:read
Permission
View the module
MCP tool
ads_visualizer_meta_ads_delivery_getOn the full surface; on the compact one, mb_execute_operation with id: "ads_visualizer.meta_ads.delivery.get".
Declared cost: up to 4 reads and 0 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.
Parameters
account_idstringpathrequired
The Meta Ads account: the Meta ad account id, with or without the act_ prefix. It must be connected to the organization (ads_visualizer.accounts.list).
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.
