API reference: Meta Ads

Meta Ads is a read + guardrailed write connector, called via tools/call over POST /meta-ads/mcp. The connector reads from and writes to Meta’s Marketing API and is connected through OAuth (Facebook Login; see Forbind Meta Ads).

Endpoint: https://mcp.consile.ai/meta-ads/mcp. Meta Ads is its own named connector with only its own tools. If your account has extra Meta Ads portals (other Meta users), each one has its own endpoint, https://mcp.consile.ai/meta-ads-2/mcp, .../meta-ads-3/mcp and so on, with tools named meta-ads-2__<tool>. The tools and guardrails are the same on every portal.

The customer must reconnect Meta Ads about every 60 days. Use list_ad_accounts as a lightweight connectivity test. When the access has expired, calls return a tool error (isError: true) whose text says the Meta access token must be reconnected (for example Meta access token has expired; reconnect required). If access was revoked in Meta, calls can instead fail with Tool invocation failed.; Meta’s own message is not forwarded. See Errors & limits.

Write safety: guardrail model

The five write tools (create_campaign, create_ad_set, create_ad, update_status, update_budget) share one guardrail:

New objects default to PAUSED. With the default status nothing spends, and the create applies immediately (no confirm needed). Passing status: "ACTIVE" (or "ARCHIVED") at creation is accepted but requires confirm: true.
Spend, budget, and archival actions require confirm: true. These are: setting status to ACTIVE (spend starts), setting status to ARCHIVED, and any budget change. Without confirm: true, the tool returns a dry-run preview and sends nothing to Meta.
Pausing is always safe. Setting status: "PAUSED" does not require confirmation.
There is no hard-delete. Removal is archival (status: "ARCHIVED").
Bids are set only at creation. bidAmountMinor exists only on create_ad_set; no tool changes a bid afterwards.

See Write tools & guardrails for how the preview and confirm work across connectors.

Preview shape

When a write action requires confirmation but confirm is omitted or false, every write tool returns this shape instead of calling Meta:

{
  "preview": {
    "action": "create_campaign",
    "summary": "Create campaign \"Summer Sale\" (objective OUTCOME_TRAFFIC) as ACTIVE.",
    "request": {
      "method": "POST",
      "path": "act_1234567890/campaigns",
      "body": {
        "name": "Summer Sale",
        "objective": "OUTCOME_TRAFFIC",
        "status": "ACTIVE",
        "special_ad_categories": "[]"
      }
    },
    "confirmHint": "Re-run the same call with confirm: true to apply this change."
  }
}

The preview is a normal successful tool result (isError is not set). To apply, re-run the identical call with confirm: true added. When applied, the tool returns Meta’s Graph response unchanged (for a create, the new object id).

Default status

All three create tools default status to PAUSED when it is omitted.

Tool hints

Read tools are annotated readOnlyHint: true, destructiveHint: false, openWorldHint: false. The five write tools are annotated readOnlyHint: false, destructiveHint: true, openWorldHint: true, so MCP clients may ask the user before running them. tools/list on this endpoint also includes the unprefixed connect_account tool, which returns a link to (re)connect Meta that is valid for 10 minutes.

Shared parameters

Ad account id

All account-scoped tools accept adAccountId in either the act_<digits> form or as bare digits. adAccountId is required on every account-scoped tool, also when you scope by campaignId, adSetId or adId (it is then not used). Other object ids (campaignId, adSetId, adId, creativeId, pageId, formId, leadId, objectId) must be bare digits.

Date window and preset

The insights tools accept either an explicit date range or a preset:

string (YYYY-MM-DD)

Start of an explicit window. Used only together with toDate; if either is missing, datePreset (default last_30d) applies.

string (YYYY-MM-DD)

End of the window. Used only together with fromDate.

string

default:"last_30d"

A Meta date preset, used when fromDate/toDate are omitted. Allowed values: today, yesterday, last_7d, last_14d, last_28d, last_30d, last_90d, this_week_mon_sun, last_week_mon_sun, this_month, last_month, this_quarter, maximum.

limit

integer

default:"100"

Maximum rows to return (1-5000, default 100). One call can return fewer rows than limit. List tools return count, data[] and Meta’s paging cursors; to read further, narrow the date range or scope, or call query with params.limit and params.after.

Money fields (minor units)

Budget and bid arguments on the write tools use minor units of the account currency (e.g. 5000 = 50.00 DKK/EUR/USD). Insights money fields (spend, cpc, cpm) are returned as Meta delivers them: decimal strings in the account currency’s major unit.

Read tools: accounts & structure (34 total)

list_ad_accounts

List the Meta ad accounts the connected login can access. Use this as the first call to discover the act_<id> required by the account-scoped tools.

integer

default:"100"

Returns: count, data[] with account_id, id, name, account_status, currency, timezone_name, business.

get_account_info

Read one ad account’s profile.

string

required

Meta ad account id (act_<digits> or bare digits).

Returns: account_id, name, account_status, currency, timezone_name, amount_spent, spend_cap, balance, business.

get_account_billing_summary

Spend posture for one account: caps, balances, prepay status, and disable reason. Does not include payment-instrument data.

string

required

Returns: spend_cap, amount_spent, balance, currency, is_prepay_account, account_status, disable_reason, min_daily_budget.

list_campaigns

List campaigns with status, objective, budgets and schedule.

string

required

string[]

Filter by effective_status. Allowed values: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES.

integer

default:"100"

Returns: id, name, objective, status, effective_status, buying_type, daily_budget, lifetime_budget, bid_strategy, start_time, stop_time, special_ad_categories, created_time, updated_time.

list_ad_sets

List ad sets. Optionally scope to one campaign.

string

required

string

Scope to one campaign id (bare digits).

integer

default:"100"

Returns: id, name, campaign_id, status, effective_status, optimization_goal, billing_event, bid_strategy, bid_amount, daily_budget, lifetime_budget, start_time, end_time, created_time, updated_time.

list_ads

List ads. Optionally scope to one ad set.

string

required

string

Scope to one ad set id.

integer

default:"100"

Returns: id, name, adset_id, campaign_id, status, effective_status, creative{id}, created_time, updated_time.

Read tools: creatives & assets

list_creatives

List ad creatives (identity-level) for the account.

string

required

integer

default:"100"

Returns: id, name, title, body, object_type, call_to_action_type, thumbnail_url, image_url, instagram_permalink_url, effective_object_story_id.

list_ad_creatives_detail

Every creative with fully hydrated content (object_story_spec, CTA, image_url, video_id, link_url, url_tags) for messaging and UTM audits.

string

required

integer

default:"100"

Returns: All fields of list_creatives plus status, object_story_id, object_story_spec, image_hash, video_id, link_url, url_tags.

get_ad_creative

Full creative detail for one creative id: what the ad says, shows or links to.

string

required

Numeric Graph creative id (bare digits).

Returns: The same hydrated fields as list_ad_creatives_detail for one creative, including object_story_spec (which carries the copy, CTA, link and the page and Instagram ids), image_url, image_hash, video_id and url_tags.

get_ad_creative_asset_feed_spec

The asset_feed_spec of a Dynamic or Advantage+ creative: candidate images, videos, bodies, titles, descriptions, link URLs, CTA options and customization rules. For dynamic ads the flat fields are empty; this is the only read of the variants.

string

required

Returns: id, name, asset_feed_spec, degrees_of_freedom_spec, object_type.

get_ad_preview

Render a placement preview of an existing ad (same render as Ads Manager).

string

required

Numeric Graph ad id.

string

default:"MOBILE_FEED_STANDARD"

A Meta ad_format enum, e.g. MOBILE_FEED_STANDARD, INSTAGRAM_STORY, FACEBOOK_REELS_MOBILE, DESKTOP_FEED_STANDARD.

Returns: Meta’s preview response unchanged (data[], each entry holding the preview iframe).

list_ad_images

Account image library with viewable URLs. Resolves a creative’s image_hash.

string

required

integer

default:"100"

Returns: hash, name, url, url_128, permalink_url, width, height, status, created_time.

Read tools: insights & performance

All insights tools accept the shared date window and preset and limit parameters. Returns: node, level, count, rows[]. Each row carries the level’s id/name fields (account: account_id, account_name; campaign: campaign_id, campaign_name; adset: adset_id, adset_name, campaign_name; ad: ad_id, ad_name, adset_name, campaign_name) plus the tool’s metrics:

Tool	Metrics
`account_insights`, `campaign_insights`, `ad_set_insights`, `ad_insights`, `insights_by_breakdown`	`impressions`, `reach`, `frequency`, `clicks`, `spend`, `ctr`, `cpc`, `cpm`, `inline_link_clicks`, `actions`, `action_values`
`get_conversion_actions`	`actions`, `action_values`, `cost_per_action_type`, `conversions`, `conversion_values`, `cost_per_conversion` (split by `action_type`)
`get_reach_and_frequency`	`reach`, `frequency`, `impressions`, `cpm`, `unique_clicks`, `unique_ctr`, `cost_per_unique_click`, `full_view_reach`, `full_view_impressions`
`get_video_metrics`	`video_play_actions`, `video_p25/p50/p75/p95/p100_watched_actions`, `video_thruplay_watched_actions`, `video_30_sec_watched_actions`, `video_avg_time_watched_actions`, `cost_per_thruplay`
`creative_asset_insights_breakdown`	`impressions`, `clicks`, `spend`, `ctr`, `actions` at level ad, broken down by image, body, title, description, call-to-action and video asset

No tool requests a ready-made ROAS field; derive it from spend and action_values.

account_insights

Account-level performance headline: impressions, reach, clicks, spend, CTR, CPC, CPM, frequency, actions.

string

required

string

default:"last_30d"

integer

default:"100"

campaign_insights

Per-campaign performance. Optionally scope to one campaign.

string

required

string

Scope to one campaign id.

string

default:"last_30d"

integer

default:"100"

ad_set_insights

Per-ad-set performance. Optionally scope to one ad set.

string

required

string

Scope to one ad set id.

string

default:"last_30d"

integer

default:"100"

ad_insights

Per-ad (finest granularity) performance. Optionally scope to one ad.

string

required

string

Scope to one ad id.

string

default:"last_30d"

integer

default:"100"

insights_by_breakdown

Performance split by a demographic, geographic or delivery dimension.

string

required

string

required

One of: age, gender, country, region, dma, publisher_platform, platform_position, impression_device, device_platform.

string

default:"account"

Aggregation level: account, campaign, adset, or ad.

string

default:"last_30d"

integer

default:"100"

get_conversion_actions

Conversions broken out by action_type (purchase, lead, add_to_cart, registration, landing_page_view) with cost_per_action_type, conversions, conversion_values, cost_per_conversion: how many leads or purchases there were and what each one cost.

string

required

string

default:"account"

string

default:"last_30d"

integer

default:"100"

get_reach_and_frequency

Deduplicated audience view: reach, frequency, unique clicks, unique CTR, cost_per_unique_click. Optional daily time series.

string

required

string

default:"account"

boolean

If true, return a per-day time series (time_increment=1).

string

default:"last_30d"

integer

default:"100"

get_video_metrics

Video-engagement funnel: plays, % watched (25/50/75/95/100), ThruPlay, 30-sec, average time watched, cost_per_thruplay.

string

required

string

default:"account"

string

default:"last_30d"

integer

default:"100"

creative_asset_insights_breakdown

Per-asset performance inside a Dynamic or Advantage+ ad: which image, video, headline, body, description, or CTA variant drives results. Ad-level only.

string

required

A single ad id (bare digits).

string

default:"last_30d"

integer

default:"100"

Read tools: tracking config

list_pixels

Meta Pixels/datasets with health metadata. Returns metadata only (no event payloads).

string

required

integer

default:"100"

Returns: id, name, last_fired_time, data_use_setting, enable_automatic_matching, is_unavailable, creation_time.

list_custom_conversions

Custom conversions and their configuration: source pixel, rule, event type, default value, archive status.

string

required

integer

default:"100"

Returns: id, name, pixel, rule, custom_event_type, default_conversion_value, is_archived, creation_time.

Read tools: audiences & planning

list_custom_audiences

Custom Audiences metadata only (Meta stores only hashes; no member data is ever returned): name, subtype, approximate size bounds, operation/delivery status.

string

required

integer

default:"100"

Returns: id, name, subtype, description, approximate_count_lower_bound, approximate_count_upper_bound, operation_status, delivery_status, retention_days, time_created, time_updated, data_source, is_value_based.

list_saved_audiences

Saved (reusable) targeting audiences with their full targeting spec, sentence_lines, and approximate size. Configuration data, not member data.

string

required

integer

default:"100"

Returns: id, name, description, targeting, approximate_count_lower_bound, approximate_count_upper_bound, run_status, sentence_lines, time_created, time_updated.

estimate_reach

Estimated reachable audience size for a targeting spec before spending. Returns an aggregate count (no individuals).

string

required

string

required

A Meta targeting_spec as a JSON string, e.g. '{"geo_locations":{"countries":["DK"]}}'. Must be valid JSON.

Returns: Meta’s reach-estimate response unchanged: an aggregate audience size and estimate_ready. No individuals.

search_targeting_interests

Search the interest-targeting taxonomy by free text.

string

required

string

required

Free-text interest query, e.g. running shoes.

integer

default:"100"

Returns: id, name, type, audience size bounds, path (breadcrumb), topic.

Read tools: account audit

list_account_activities

Account change log: budget edits, status flips, targeting changes.

string

required

string (YYYY-MM-DD)

Only events on or after this date.

string (YYYY-MM-DD)

Only events on or before this date.

integer

default:"100"

Returns: event_type, translated_event_type, event_time, object_id, object_name, actor_id, actor_name, extra_data.

list_automated_rules

Automated ad rules: triggers, filters, scheduled action (pause/scale/etc.). Shows what automation is running and what it would do.

string

required

integer

default:"100"

Returns: id, name, status, evaluation_spec, execution_spec, schedule_spec, created_by.

Read tools: leads & pages

Lead field_data carries personal data (name, email, phone). Leads are fetched from Meta when requested and returned to your AI assistant; Consile does not store them. See GDPR & dine rettigheder.

list_pages

List the Facebook Pages the connected user manages. The first call for the leads workflow: lead forms live on a Page.

integer

default:"100"

Returns: id, name, category, tasks.

list_lead_forms

List the Lead-Ads forms on a Page.

string

required

A Page id (from list_pages).

integer

default:"100"

Returns: id, name, status, locale, created_time, leads_count.

list_leads

Read the leads captured by a lead form.

string

required

A lead form id (from list_lead_forms).

integer

default:"100"

Returns: id, created_time, ad_id, adset_id, campaign_id, form_id, platform, field_data (submitted answers; may contain personal data).

get_lead

Read one lead by id.

string

required

A lead id (from list_leads).

Returns: Same fields as list_leads for the single record.

Read tools: advanced / escape hatch

query

Advanced read of any Graph node or edge, for reads that no dedicated tool covers. It is read-only: it cannot create or change anything.

string

required

A bare Graph path without a query string, e.g. act_1234567890/campaigns or 23847239847. Pass parameters in params.

object

Read params. Supported keys: fields, time_range, date_preset, level, breakdowns, action_breakdowns, filtering, time_increment, limit (at most 5000), after, sort, effective_status.

Returns: the raw Graph response for one page (for edges: data and paging). Use params.after with the returned cursor to read the next page.

Write tools (5 guardrailed)

Write tools call the Meta Marketing API. New objects are created PAUSED and never spend until you activate them. Activating (ACTIVE, which starts spend), changing a budget or archiving requires confirm: true. Without it the tool returns a preview and sends nothing to Meta. See Write tools & guardrails.

create_campaign

Create a new campaign. Created PAUSED by default.

string

required

string

required

Campaign name.

string

required

Campaign objective (ODAX). One of: OUTCOME_TRAFFIC, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.

string

default:"PAUSED"

Initial status. ACTIVE requires confirm: true.

string[]

default:"[]"

Special ad categories, e.g. HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS. Pass [] if none. Validated by Meta.

boolean

Set true to apply when status is ACTIVE (starts spend) or ARCHIVED. Omit or false to receive a preview.

Requires confirmation: only when status is ACTIVE or ARCHIVED.

create_ad_set

Create an ad set under a campaign. Created PAUSED by default.

string

required

string

required

Parent campaign id (bare digits).

string

required

integer

Daily budget in minor units (e.g. 5000 = 50.00). Provide exactly one of dailyBudgetMinor and lifetimeBudgetMinor; neither or both is rejected.

integer

Lifetime budget in minor units.

string

required

e.g. IMPRESSIONS, LINK_CLICKS, THRUPLAY, POST_ENGAGEMENT. Validated by Meta.

string

required

e.g. LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, REACH, THRUPLAY. Validated by Meta, which rejects invalid combinations.

string

required

Meta targeting_spec as a JSON string, e.g. '{"geo_locations":{"countries":["DK"]}}'. Must be valid JSON.

integer

Bid cap in minor units (optional). This is the only place a bid can be set.

string

ISO 8601 start time (optional).

string

ISO 8601 end time (optional).

string

default:"PAUSED"

Initial status. ACTIVE requires confirm: true.

boolean

Requires confirmation: when status is ACTIVE or ARCHIVED.

create_ad

Create an ad under an ad set from an existing creative. Created PAUSED by default.

string

required

string

required

Parent ad set id (bare digits).

string

required

string

required

An existing ad creative id (from list_creatives). Building creatives from scratch (image/video upload) is not supported by this connector.

string

default:"PAUSED"

Initial status. ACTIVE requires confirm: true.

boolean

Requires confirmation: when status is ACTIVE or ARCHIVED.

update_status

Set a campaign, ad set, or ad to PAUSED, ACTIVE, or ARCHIVED.

string

required

A campaign, ad set, or ad id (bare digits).

string

required

Target status: ACTIVE, PAUSED, or ARCHIVED.

boolean

Requires confirmation: ACTIVE (spend starts) and ARCHIVED. Pausing (PAUSED) applies immediately (no confirmation needed).

update_budget

Change the daily or lifetime budget of a campaign or ad set. Always requires confirmation (it changes spend).

string

required

A campaign or ad set id (bare digits).

integer

New daily budget in minor units. Provide exactly one of dailyBudgetMinor and lifetimeBudgetMinor; neither or both is rejected.

integer

New lifetime budget in minor units.

boolean

Optional in the schema, but must be true to apply a budget change. Omit (or false) to receive a preview.

Always requires confirmation.

Code examples

{
  "name": "meta-ads__list_campaigns",
  "arguments": {
    "adAccountId": "act_1234567890",
    "effectiveStatus": ["ACTIVE"],
    "limit": 50
  }
}

{
  "name": "meta-ads__campaign_insights",
  "arguments": {
    "adAccountId": "act_1234567890",
    "datePreset": "last_30d"
  }
}

{
  "name": "meta-ads__create_campaign",
  "arguments": {
    "adAccountId": "act_1234567890",
    "name": "Summer Sale 2026",
    "objective": "OUTCOME_TRAFFIC",
    "status": "ACTIVE"
  }
}

{
  "name": "meta-ads__create_campaign",
  "arguments": {
    "adAccountId": "act_1234567890",
    "name": "Summer Sale 2026",
    "objective": "OUTCOME_TRAFFIC",
    "status": "ACTIVE",
    "confirm": true
  }
}

{
  "name": "meta-ads__update_status",
  "arguments": {
    "objectId": "23847239847",
    "status": "ACTIVE",
    "confirm": true
  }
}

The preview/apply pair above uses status: "ACTIVE" because only that status (or ARCHIVED) needs confirmation on create. A create_campaign with the default status PAUSED (or with status omitted) needs no confirm and applies directly: it creates the paused object rather than returning a preview.

Tool names are namespaced meta-ads__<tool> in Claude/ChatGPT (the AI invokes these automatically). The bare names (e.g. list_campaigns) are used here for readability.

Meta failures reach the client as a tool result with isError: true and the fixed text Tool invocation failed. This covers Meta validation errors and the connector’s own argument checks (for example both budgets given, or targeting that is not valid JSON). When the access has expired, the text instead ends in reconnect required; a revoked access can also show up as Tool invocation failed. If every call fails, reconnect Meta Ads in the portal, or call the connect_account tool on this endpoint to get a fresh connect link. See Errors & limits.

​Write safety: guardrail model

​Preview shape

​Default status

​Tool hints

​Shared parameters

​Ad account id

​Date window and preset

​limit

​Money fields (minor units)

​Read tools: accounts & structure (34 total)

​list_ad_accounts

​get_account_info

​get_account_billing_summary

​list_campaigns

​list_ad_sets

​list_ads

​Read tools: creatives & assets

​list_creatives

​list_ad_creatives_detail

​get_ad_creative

​get_ad_creative_asset_feed_spec

​get_ad_preview

​list_ad_images

​Read tools: insights & performance

​account_insights

​campaign_insights

​ad_set_insights

​ad_insights

​insights_by_breakdown

​get_conversion_actions

​get_reach_and_frequency

​get_video_metrics

​creative_asset_insights_breakdown

​Read tools: tracking config

​list_pixels

​list_custom_conversions

​Read tools: audiences & planning

​list_custom_audiences

​list_saved_audiences

​estimate_reach

​search_targeting_interests

​Read tools: account audit

​list_account_activities

​list_automated_rules

​Read tools: leads & pages

​list_pages

​list_lead_forms

​list_leads

​get_lead

​Read tools: advanced / escape hatch

​query

​Write tools (5 guardrailed)

​create_campaign

​create_ad_set

​create_ad

​update_status

​update_budget

​Code examples

Write safety: guardrail model

Preview shape

Default status

Tool hints

Shared parameters

Ad account id

Date window and preset

limit

Money fields (minor units)

Read tools: accounts & structure (34 total)

list_ad_accounts

get_account_info

get_account_billing_summary

list_campaigns

list_ad_sets

list_ads

Read tools: creatives & assets

list_creatives

list_ad_creatives_detail

get_ad_creative

get_ad_creative_asset_feed_spec

get_ad_preview

list_ad_images

Read tools: insights & performance

account_insights

campaign_insights

ad_set_insights

ad_insights

insights_by_breakdown

get_conversion_actions

get_reach_and_frequency

get_video_metrics

creative_asset_insights_breakdown

Read tools: tracking config

list_pixels

list_custom_conversions

Read tools: audiences & planning

list_custom_audiences

list_saved_audiences

estimate_reach

search_targeting_interests

Read tools: account audit

list_account_activities

list_automated_rules

Read tools: leads & pages

list_pages

list_lead_forms

list_leads

get_lead

Read tools: advanced / escape hatch

query

Write tools (5 guardrailed)

create_campaign

create_ad_set

create_ad

update_status

update_budget

Code examples