> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consile.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference: Meta Ads

> All 39 tools in the Meta Ads connector: 34 read tools covering accounts, creatives, insights, audiences and leads; 5 guardrailed write tools for creating and managing campaigns. WritePreview dry-run semantics and confirm:true contract documented.

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](/connect/forbind-meta-ads)).

<Info>
  Endpoint: `https://mcp.consile.ai/meta-ads/mcp`. Meta Ads is its own named
  connector with only its own tools.
</Info>

<Warning>
  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](/developers/errors-and-limits).
</Warning>

***

## Write safety: guardrail model

The five write tools (`create_campaign`, `create_ad_set`, `create_ad`,
`update_status`, `update_budget`) share a connector-local guardrail:

1. **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`.
2. **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.
3. **Pausing is always safe.** Setting `status: "PAUSED"` does not require
   confirmation.
4. **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](/essentials/handlinger-og-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:

```json theme={null}
{
  "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:

<ParamField path="fromDate" type="string (YYYY-MM-DD)">
  Start of an explicit window. Must be paired with `toDate`.
</ParamField>

<ParamField path="toDate" type="string (YYYY-MM-DD)">
  End of the window.
</ParamField>

<ParamField path="datePreset" type="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`.
</ParamField>

### limit

<ParamField path="limit" type="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.
</ParamField>

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

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required>
  Meta ad account id (`act_<digits>` or bare digits).
</ParamField>

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

<ParamField path="adAccountId" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="effectiveStatus" type="string[]">
  Filter by `effective_status`. Allowed values: `ACTIVE`, `PAUSED`, `DELETED`,
  `ARCHIVED`, `IN_PROCESS`, `WITH_ISSUES`.
</ParamField>

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="campaignId" type="string">
  Scope to one campaign id (bare digits).
</ParamField>

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="adSetId" type="string">
  Scope to one ad set id.
</ParamField>

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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.

<ParamField path="creativeId" type="string" required>
  Numeric Graph creative id (bare digits).
</ParamField>

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

<ParamField path="creativeId" type="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).

<ParamField path="adId" type="string" required>
  Numeric Graph ad id.
</ParamField>

<ParamField path="adFormat" type="string" default="MOBILE_FEED_STANDARD">
  A Meta `ad_format` enum, e.g. `MOBILE_FEED_STANDARD`, `INSTAGRAM_STORY`,
  `FACEBOOK_REELS_MOBILE`, `DESKTOP_FEED_STANDARD`.
</ParamField>

**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`.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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](#date-window--preset) and
`limit` parameters.

### account\_insights

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

<ParamField path="adAccountId" type="string" required />

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="integer" default="100" />

***

### campaign\_insights

Per-campaign performance. Optionally scope to one campaign.

<ParamField path="adAccountId" type="string" required />

<ParamField path="campaignId" type="string">Scope to one campaign id.</ParamField>

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="integer" default="100" />

***

### ad\_set\_insights

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

<ParamField path="adAccountId" type="string" required />

<ParamField path="adSetId" type="string">Scope to one ad set id.</ParamField>

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="integer" default="100" />

***

### ad\_insights

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

<ParamField path="adAccountId" type="string" required />

<ParamField path="adId" type="string">Scope to one ad id.</ParamField>

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="integer" default="100" />

***

### insights\_by\_breakdown

Performance split by a demographic, geographic or delivery dimension.

<ParamField path="adAccountId" type="string" required />

<ParamField path="breakdown" type="string" required>
  One of: `age`, `gender`, `country`, `region`, `dma`, `publisher_platform`,
  `platform_position`, `impression_device`, `device_platform`.
</ParamField>

<ParamField path="level" type="string" default="account">
  Aggregation level: `account`, `campaign`, `adset`, or `ad`.
</ParamField>

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="level" type="string" default="account" />

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="integer" default="100" />

***

### get\_reach\_and\_frequency

Deduplicated audience view: reach, frequency, unique clicks, unique CTR,
cost\_per\_unique\_click. Optional daily time series.

<ParamField path="adAccountId" type="string" required />

<ParamField path="level" type="string" default="account" />

<ParamField path="daily" type="boolean">
  If `true`, return a per-day time series (`time_increment=1`).
</ParamField>

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="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`.

<ParamField path="adAccountId" type="string" required />

<ParamField path="level" type="string" default="account" />

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="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.

<ParamField path="adId" type="string" required>
  A single ad id (bare digits).
</ParamField>

<ParamField path="fromDate" type="string" />

<ParamField path="toDate" type="string" />

<ParamField path="datePreset" type="string" default="last_30d" />

<ParamField path="limit" type="integer" default="100" />

***

## Read tools: tracking config

### list\_pixels

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

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="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).

<ParamField path="adAccountId" type="string" required />

<ParamField path="targetingSpec" type="string" required>
  A Meta `targeting_spec` as a JSON string,
  e.g. `'{"geo_locations":{"countries":["DK"]}}'`.
</ParamField>

**Returns:** `users` (aggregate estimate), `estimate_ready`.

***

### search\_targeting\_interests

Search the interest-targeting taxonomy by free text.

<ParamField path="adAccountId" type="string" required />

<ParamField path="query" type="string" required>
  Free-text interest query, e.g. `running shoes`.
</ParamField>

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="since" type="string (YYYY-MM-DD)">
  Only events on or after this date.
</ParamField>

<ParamField path="until" type="string (YYYY-MM-DD)">
  Only events on or before this date.
</ParamField>

<ParamField path="limit" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="limit" type="integer" default="100" />

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

***

## Read tools: leads & pages

<Note>
  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.
</Note>

### list\_pages

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

<ParamField path="limit" type="integer" default="100" />

**Returns:** `id`, `name`, `category`, `tasks`.

***

### list\_lead\_forms

List the Lead-Ads forms on a Page.

<ParamField path="pageId" type="string" required>
  A Page id (from `list_pages`).
</ParamField>

<ParamField path="limit" type="integer" default="100" />

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

***

### list\_leads

Read the leads captured by a lead form.

<ParamField path="formId" type="string" required>
  A lead form id (from `list_lead_forms`).
</ParamField>

<ParamField path="limit" type="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.

<ParamField path="leadId" type="string" required>
  A lead id (from `list_leads`).
</ParamField>

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

<ParamField path="path" type="string" required>
  A bare Graph path, e.g. `act_1234567890/campaigns` or `23847239847`. No scheme,
  no `..`, no query string.
</ParamField>

<ParamField path="params" type="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`.
</ParamField>

***

## Write tools (5 guardrailed)

<Warning>
  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](#writepreview-shape) and calls no API. See
  [Handlinger & guardrails](/essentials/handlinger-og-guardrails).
</Warning>

### create\_campaign

Create a new campaign. Created `PAUSED` by default.

<ParamField path="adAccountId" type="string" required />

<ParamField path="name" type="string" required>
  Campaign name.
</ParamField>

<ParamField path="objective" type="string" required>
  Campaign objective (ODAX). One of: `OUTCOME_TRAFFIC`, `OUTCOME_AWARENESS`,
  `OUTCOME_ENGAGEMENT`, `OUTCOME_LEADS`, `OUTCOME_SALES`, `OUTCOME_APP_PROMOTION`.
</ParamField>

<ParamField path="status" type="string" default="PAUSED">
  Initial status. `ACTIVE` requires `confirm: true`.
</ParamField>

<ParamField path="specialAdCategories" type="string[]" default="[]">
  Special ad categories, e.g. `HOUSING`, `EMPLOYMENT`, `CREDIT`,
  `ISSUES_ELECTIONS_POLITICS`. Pass `[]` if none.
</ParamField>

<ParamField path="confirm" type="boolean">
  Set `true` to apply when `status` is `ACTIVE` (starts spend) or `ARCHIVED`.
  Omit or `false` to receive a WritePreview.
</ParamField>

**Requires confirmation:** only when `status` is `ACTIVE` or `ARCHIVED`.

***

### create\_ad\_set

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

<ParamField path="adAccountId" type="string" required />

<ParamField path="campaignId" type="string" required>
  Parent campaign id (bare digits).
</ParamField>

<ParamField path="name" type="string" required />

<ParamField path="dailyBudgetMinor" type="integer">
  Daily budget in minor units (e.g. `5000` = 50.00). Provide **daily OR lifetime**.
</ParamField>

<ParamField path="lifetimeBudgetMinor" type="integer">
  Lifetime budget in minor units.
</ParamField>

<ParamField path="billingEvent" type="string" required>
  e.g. `IMPRESSIONS`, `LINK_CLICKS`, `THRUPLAY`, `POST_ENGAGEMENT`.
</ParamField>

<ParamField path="optimizationGoal" type="string" required>
  e.g. `LINK_CLICKS`, `LANDING_PAGE_VIEWS`, `OFFSITE_CONVERSIONS`, `REACH`,
  `THRUPLAY`.
</ParamField>

<ParamField path="targeting" type="string" required>
  Meta `targeting_spec` as a JSON string,
  e.g. `'{"geo_locations":{"countries":["DK"]}}'`.
</ParamField>

<ParamField path="bidAmountMinor" type="integer">
  Bid cap in minor units (optional).
</ParamField>

<ParamField path="startTime" type="string">
  ISO 8601 start time (optional).
</ParamField>

<ParamField path="endTime" type="string">
  ISO 8601 end time (optional).
</ParamField>

<ParamField path="status" type="string" default="PAUSED">
  Initial status. `ACTIVE` requires `confirm: true`.
</ParamField>

<ParamField path="confirm" type="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.

<ParamField path="adAccountId" type="string" required />

<ParamField path="adSetId" type="string" required>
  Parent ad set id (bare digits).
</ParamField>

<ParamField path="name" type="string" required />

<ParamField path="creativeId" type="string" required>
  An existing ad creative id (from `list_creatives`). Building creatives from
  scratch (image/video upload) is not supported by this connector.
</ParamField>

<ParamField path="status" type="string" default="PAUSED">
  Initial status. `ACTIVE` requires `confirm: true`.
</ParamField>

<ParamField path="confirm" type="boolean" />

**Requires confirmation:** when `status` is `ACTIVE` or `ARCHIVED`.

***

### update\_status

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

<ParamField path="objectId" type="string" required>
  A campaign, ad set, or ad id (bare digits).
</ParamField>

<ParamField path="status" type="string" required>
  Target status: `ACTIVE`, `PAUSED`, or `ARCHIVED`.
</ParamField>

<ParamField path="confirm" type="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).

<ParamField path="objectId" type="string" required>
  A campaign or ad set id (bare digits).
</ParamField>

<ParamField path="dailyBudgetMinor" type="integer">
  New daily budget in minor units. Provide **daily OR lifetime**.
</ParamField>

<ParamField path="lifetimeBudgetMinor" type="integer">
  New lifetime budget in minor units.
</ParamField>

<ParamField path="confirm" type="boolean">
  Optional in the schema, but must be `true` to apply a budget change. Omit (or
  `false`) to receive a WritePreview.
</ParamField>

**Always requires confirmation.**

***

## Code examples

<CodeGroup>
  ```json Request: list_campaigns (active only) theme={null}
  {
    "name": "meta-ads__list_campaigns",
    "arguments": {
      "adAccountId": "act_1234567890",
      "effectiveStatus": ["ACTIVE"],
      "limit": 50
    }
  }
  ```

  ```json Request: campaign_insights (last 30 days) theme={null}
  {
    "name": "meta-ads__campaign_insights",
    "arguments": {
      "adAccountId": "act_1234567890",
      "datePreset": "last_30d"
    }
  }
  ```

  ```json Request: create_campaign (dry-run preview) theme={null}
  {
    "name": "meta-ads__create_campaign",
    "arguments": {
      "adAccountId": "act_1234567890",
      "name": "Summer Sale 2026",
      "objective": "OUTCOME_TRAFFIC",
      "status": "ACTIVE"
    }
  }
  ```

  ```json Request: create_campaign (apply with confirm) theme={null}
  {
    "name": "meta-ads__create_campaign",
    "arguments": {
      "adAccountId": "act_1234567890",
      "name": "Summer Sale 2026",
      "objective": "OUTCOME_TRAFFIC",
      "status": "ACTIVE",
      "confirm": true
    }
  }
  ```

  ```json Request: update_status → ACTIVE (requires confirm) theme={null}
  {
    "name": "meta-ads__update_status",
    "arguments": {
      "objectId": "23847239847",
      "status": "ACTIVE",
      "confirm": true
    }
  }
  ```
</CodeGroup>

<Note>
  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.
</Note>

<Note>
  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.
</Note>

<Note>
  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](/developers/errors-and-limits).
</Note>