List the Meta Ads campaigns of a connected account
ads_visualizer.meta_ads.campaigns.list
LeituraIdempotenteDesde 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).
Instruções para agentes
Report state as the campaign's status: an enabled campaign past its end date reads finished, and paused wins over everything.
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_campaigns_listNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.campaigns.list".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
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).
statusenumqueryopcional
enabled (or active, the same), paused or all (both; the default). Removed, archived and deleted items never come.
Valores: all, enabled, paused, active · Padrão: "all"
searchstringqueryopcional
Part of the name (case-insensitive) or the exact id.
limitintegerqueryopcional
Page size, 1 to 200 (default 50).
Padrão: 50
cursorstringqueryopcional
next_cursor of the previous page, with the same filters.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 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).
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_campaigns_getNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.campaigns.get".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
The ad account, as ads_visualizer.accounts.list gives it (it must be connected to the organization).
campaign_idstringrotaobrigatório
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…).
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 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).
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_ad_groups_getNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.ad_groups.get".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
The ad account, as ads_visualizer.accounts.list gives it (it must be connected to the organization).
ad_group_idstringrotaobrigatório
The ad group or ad set (id from the ad_groups.list operation of the same platform).
Resposta
platformenum
Valores: 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.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 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).
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_ad_groups_listNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.ad_groups.list".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
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).
statusenumqueryopcional
enabled (or active, the same), paused or all (both; the default). Removed, archived and deleted items never come.
Valores: all, enabled, paused, active · Padrão: "all"
searchstringqueryopcional
Part of the name (case-insensitive) or the exact id.
limitintegerqueryopcional
Page size, 1 to 200 (default 50).
Padrão: 50
cursorstringqueryopcional
next_cursor of the previous page, with the same filters.
campaign_idstringqueryopcional
Only the groups of this campaign. Default: every group of the account.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.
List the ads of a Meta Ads ad set with their creative
ads_visualizer.meta_ads.ads.list
LeituraIdempotenteDesde 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).
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_ads_listNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.ads.list".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
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_idstringrotaobrigatório
The ad set (id from ads_visualizer.meta_ads.ad_groups.list).
statusenumqueryopcional
enabled (or active, the same), paused or all (both; the default). Removed, archived and deleted items never come.
Valores: all, enabled, paused, active · Padrão: "all"
searchstringqueryopcional
Part of the name (case-insensitive) or the exact id.
limitintegerqueryopcional
Page size, 1 to 200 (default 50).
Padrão: 50
cursorstringqueryopcional
next_cursor of the previous page, with the same filters.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.
Get the performance of each ad of a Meta Ads ad set
ads_visualizer.meta_ads.metrics.get
LeituraIdempotenteDesde 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).
Instruções para agentes
Costs are in the account's currency (the currency field): name it. An ad missing from data had no impressions in the range.
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_metrics_getNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.metrics.get".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
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_idstringrotaobrigatório
The ad set (id from ads_visualizer.meta_ads.ad_groups.list).
periodenumqueryopcional
7d, 14d or 30d (default): that many complete days ending yesterday. Ignored when start_date and end_date come.
Valores: 7d, 14d, 30d · Padrão: "30d"
start_datestringqueryopcional
First day of the range (YYYY-MM-DD, in the account's time zone). Send it with end_date.
end_datestringqueryopcional
Last day of the range (YYYY-MM-DD, included). At most 400 days after start_date.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.
Get the impressions of the last 7 days of each Meta Ads campaign
ads_visualizer.meta_ads.delivery.get
LeituraIdempotenteDesde 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).
Escopo
ads_visualizer:read
Permissão
Ver o módulo
Tool do MCP
ads_visualizer_meta_ads_delivery_getNa superfície completa; na compacta, mb_execute_operation com id: "ads_visualizer.meta_ads.delivery.get".
Custo declarado: até 4 leituras e 0 escritas por chamada (contam na cota diária). Usa uma plataforma externa (meta): conta na cota de operações externas.
Parâmetros
account_idstringrotaobrigatório
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).
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.
