API reference: Meta Ads

Meta Ads is a read + guardrailed write connector, called via tools/call over POST /meta-ads/mcp. The connector talks to Meta’s Graph Marketing API (version v25.0) 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.

Meta issues long-lived access tokens (~60-day expiry) via fb_exchange_token. There is no refresh_token. When the token expires, reconnect is required. Use list_ad_accounts as a lightweight connectivity test; a 401 from Meta surfaces as AccessTokenExpiredError. See Errors & limits.

Write safety: guardrail model

The five write tools (create_campaign, create_ad_set, create_ad, update_status, update_budget) share a connector-local 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 (permanent disable), and any budget change. Without confirm: true, the tool returns a WritePreview dry-run and calls no Meta API.
Pausing is always safe. Setting status: "PAUSED" does not require confirmation.
There is no hard-delete. Removal is archival (status: "ARCHIVED").

This is a designed-in safety default (connector-local application logic), not an unbreakable platform gate. See Handlinger & guardrails for the full cross-connector policy.

WritePreview 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."
  }
}

To apply, re-run the identical call with confirm: true added.

CREATE_DEFAULT_STATUS

The default initial status for all create tools is PAUSED. The connector enforces this as a defense-in-depth fallback even if status is absent in the call.

Shared parameters

Ad account id

All account-scoped tools accept adAccountId in either the act_<digits> form or as bare digits. The connector normalizes to act_<digits> before calling the Graph API.

Date window / preset

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

string (YYYY-MM-DD)

Start of an explicit window. Must be paired with toDate.

string (YYYY-MM-DD)

End of the window.

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. The client paginates internally (cursor-based, up to 25 pages) and caps at 5000. Default 100. Each Graph call has a 15-second timeout.

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 all other 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.

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 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 does this ad actually say, show, or link to.

string

required

Numeric Graph creative id (bare digits).

Returns: Full hydrated creative including object_story_spec, CTA, image_url, image_hash, video_id, url_tags, page and Instagram ids.

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: An array of preview iframe bodies from the Graph /previews edge.

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 / preset and limit parameters.

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/purchases and what did each 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, 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.

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"]}}'.

Returns: users (aggregate estimate), estimate_ready.

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). The platform is read-through only: leads are fetched on demand and returned to your AI assistant; they are never persisted by Consile.

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: GET any Graph node or edge with a safelisted set of read parameters. Read-only by construction (GET-only). For the long tail not covered by a dedicated tool.

string

required

A bare Graph path, e.g. act_1234567890/campaigns or 23847239847. No scheme, no .., no query string.

object

Read params; only safelisted keys are forwarded (all others are dropped). Allowed keys: fields, time_range, date_preset, level, breakdowns, action_breakdowns, filtering, time_increment, limit, after, sort, effective_status.

Write tools (5 guardrailed)

Write tools call the Meta Marketing API. New objects are created PAUSED and never spend until you activate them. Any action that changes spend (→ACTIVE), changes a budget, or archives requires confirm: true. Without it the tool returns a WritePreview and calls no API. See Handlinger & 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.

boolean

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

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 daily OR lifetime.

integer

Lifetime budget in minor units.

string

required

e.g. IMPRESSIONS, LINK_CLICKS, THRUPLAY, POST_ENGAGEMENT.

string

required

e.g. LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, REACH, THRUPLAY.

string

required

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

integer

Bid cap in minor units (optional).

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 (permanent disable). Pausing (PAUSED) is immediately safe (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 daily OR lifetime.

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 WritePreview.

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 that is what actually gates. A create_campaign with the default status PAUSED (or with status omitted) needs no confirm and executes immediately: it creates the paused object rather than returning a WritePreview.

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.

An expired or revoked access token returns AccessTokenExpiredError (“Meta access token has expired; reconnect required”). Reconnect via the portal to issue a new long-lived token. See Errors & limits.

​Write safety: guardrail model

​WritePreview shape

​CREATE_DEFAULT_STATUS

​Shared parameters

​Ad account id

​Date window / 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

WritePreview shape

CREATE_DEFAULT_STATUS

Shared parameters

Ad account id

Date window / 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