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

# Meta Ads

> Ad data, performance, audiences and leads from Facebook and Instagram, plus creating and managing campaigns with confirmation, directly from your AI.

*[Læs siden på dansk](https://docs.consile.ai/connectors/meta-ads.md)*

The Meta Ads connector gives your AI access to your ads on Facebook and
Instagram (Marketing API): campaign, ad set and ad performance,
conversions, reach, video engagement, audiences, pixels and Lead Ads.
It can also create and manage campaigns for you behind clear
guardrails. You approve the Consile app via Facebook login, and your AI never
sees the access token itself.

> [!NOTE]
>
> **Read + guardrailed write.** The read tools change nothing. The three
> create tools make new objects paused (`PAUSED`) by default; creating as
> `ACTIVE`, changing budget, activating or archiving requires your explicit
> confirmation (`confirm: true`). See
> [Actions & guardrails](https://docs.consile.ai/en/essentials/actions-and-guardrails.md).

> **Access**
>
> Read + guardrailed write

> **Authentication**
>
> Meta login (OAuth)

> **Hosting**
>
> Hosted in the EU · Frankfurt

* **Price:** 299 DKK/month excl. VAT. No lock-in,
  cancel at any time. The price covers 1 user and 1 connected Meta login
  (agreement). Each extra user and each extra agreement costs 149.50 DKK/month excl.
  VAT. Also included in [the Consile Studio membership](https://docs.consile.ai/en/portal/membership.md) and
  [the free edition](https://docs.consile.ai/en/portal/free-edition.md). See [Pricing](https://docs.consile.ai/en/portal/pricing.md).
* **Users:** whoever buys Meta Ads automatically gets the included access.
  If more colleagues need Meta Ads in their AI, an administrator gives them
  access under **Team** in the portal (choose **All tools** or **Custom**
  next to Meta Ads on the person's page). An extra user is billed
  pro rata from the day access is given. A colleague without access can still
  see the tools in their AI, but
  every call is refused with a message to ask an administrator for access. One
  access covers all your Meta Ads agreements. If you have
  [the Consile Studio membership](https://docs.consile.ai/en/portal/membership.md), an administrator
  instead gives one membership licence per person, and it also covers Meta Ads. See
  [Team](https://docs.consile.ai/en/portal/team.md).
* **Multiple Meta logins and ad accounts:** the portal calls each connection to
  the system an agreement. One agreement gives access to the ad accounts and Pages that the
  connected Meta user has access to, and that you gave access to in Meta's dialog. You
  need one more agreement if you want to connect another Meta user, or if
  each ad account should have its own connection, locked to exactly that account (see
  the section on locking below). An administrator clicks **Add agreement** on the
  **Connections** card on the Meta Ads page in the portal. Each agreement gets its own address,
  for example `https://mcp.consile.ai/meta-ads-2/mcp`, which you add in your AI as a
  separate connector. If you connect the same Meta user on two agreements without locking
  them, it does not give access to more. Under
  [the Consile Studio membership](https://docs.consile.ai/en/portal/membership.md#one-more-agreement-in-a-system)
  there is no button to add an agreement, so write to
  [support@consile.dk](mailto:support@consile.dk) instead. See
  [Connect Meta Ads](https://docs.consile.ai/en/connect/connect-meta-ads.md#multiple-meta-logins-and-ad-accounts).
* **Endpoint:** `https://mcp.consile.ai/meta-ads/mcp` (your own named connector in Claude).

## Prerequisites

**1. Connector bought**

An administrator buys Meta Ads in the [portal](https://app.consile.ai): open
**Marketplace**, choose **Meta Ads** and click **Add connector**. See
[Buy a connector](https://docs.consile.ai/en/portal/buy-a-connector.md).

**2. Your AI connected**

See [Connect Claude](https://docs.consile.ai/en/connect/connect-claude.md) or
[Connect ChatGPT](https://docs.consile.ai/en/connect/connect-chatgpt.md).

**3. Meta connected**

Click **Connect now** on the Meta Ads page in the portal, log in with Facebook and
approve all the permissions the Consile app asks for. Expect to connect
Meta Ads again about every 60 days. See [Connect Meta Ads](https://docs.consile.ai/en/connect/connect-meta-ads.md).

## What can it do? (tools)

You do not need to know the tool names. You ask in natural language, and your AI
picks and calls the right tool itself. The tools are called `meta-ads__<tool>`
(for example `meta-ads__account_insights`) when your AI calls them; below, the bare
names are shown for readability.

The connector provides **39 tools** in total: 34 read-only (pure
reading) and 5 guardrailed write tools. Typically your AI starts with
`list_ad_accounts` to find the `act_<id>` that the rest of the tools use.

### Reading (34 read-only)

**Accounts & structure**

| Tool | What it does |
| - | - |
| `list_ad_accounts` | Ad accounts the login can see: id, name, status, currency, time zone |
| `get_account_info` | One account's profile: status, currency, spend, spend\_cap, balance, owner |
| `get_account_billing_summary` | Spend status: spend\_cap, spent, balance, prepay, min. daily budget |
| `list_campaigns` | Campaigns: name, objective, status, budgets, schedule (filter by status) |
| `list_ad_sets` | Ad sets: optimization goal, billing event, bid, budgets, schedule |
| `list_ads` | Ads: name, status, linked creative, optionally scoped to one ad set |

**Creatives & assets**

| Tool | What it does |
| - | - |
| `list_creatives` | Ad creatives at identity level: title, body, CTA, thumbnails |
| `list_ad_creatives_detail` | All creatives with full content (object\_story\_spec, link, UTM) for audit |
| `get_ad_creative` | One creative in full detail: what the ad says, shows and links to |
| `get_ad_creative_asset_feed_spec` | The variants in a dynamic/flexible creative (images, texts, CTAs) |
| `get_ad_preview` | Preview of an existing ad in a chosen placement |
| `list_ad_images` | The account's image library; looks up a creative's image\_hash to a URL |

**Performance & insights**

| Tool | What it does |
| - | - |
| `account_insights` | Account overview: impressions, reach, clicks, spend, ctr, cpc, cpm, frequency |
| `campaign_insights` | Performance per campaign (optionally scoped to one campaign) |
| `ad_set_insights` | Performance per ad set (optionally scoped to one ad set) |
| `ad_insights` | Performance per ad, finest granularity |
| `insights_by_breakdown` | Broken down by age, gender, country, region, platform, placement or device |
| `get_conversion_actions` | Conversions per action\_type (purchase, lead, add\_to\_cart) + cost per action |
| `get_reach_and_frequency` | Unique reach and frequency (optionally as a daily time series) |
| `get_video_metrics` | Video funnel: plays, % watched, ThruPlay, avg. watch time, cost per ThruPlay |
| `creative_asset_insights_breakdown` | Which image/text/CTA variant drives results in a dynamic ad |

**Tracking & configuration**

| Tool | What it does |
| - | - |
| `list_pixels` | Meta pixels/datasets with health data (last fired, matching), metadata only |
| `list_custom_conversions` | Custom conversions and their rules: what the numbers count |

**Audiences & planning**

| Tool | What it does |
| - | - |
| `list_custom_audiences` | Custom Audiences, metadata only (Meta only stores hashes; never members) |
| `list_saved_audiences` | Saved audiences with targeting spec and readable sentence\_lines |
| `estimate_reach` | Estimated audience size for a targeting spec *before* spend (aggregated only) |
| `search_targeting_interests` | Search the interest taxonomy for free text (id, name, size, path) |

**Audit & change log**

| Tool | What it does |
| - | - |
| `list_account_activities` | The account's change log: budget changes, status changes, targeting, audit trail |
| `list_automated_rules` | Automated ad rules: triggers, filters and which action they perform |

**Leads (Lead Ads)**

| Tool | What it does |
| - | - |
| `list_pages` | Facebook Pages the login administers (the first call before the leads tools) |
| `list_lead_forms` | Lead Ads forms on a Page: name, status, leads\_count |
| `list_leads` | Leads captured by a form incl. field\_data (the submitted answers) |
| `get_lead` | One lead in detail |

> [!WARNING]
>
> `list_leads` and `get_lead` return personal data (name, email, phone from
> field\_data). Leads are fetched directly from Meta when your AI asks for them, and are not stored
> at Consile. See [GDPR & your rights](https://docs.consile.ai/en/essentials/gdpr.md).

**Advanced**

| Tool | What it does |
| - | - |
| `query` | Advanced reading of data in Meta that the other tools do not cover; can only read |

### Writing (5 guardrailed tools)

These five tools are the only ones that change anything in your Meta account. New objects
are created `PAUSED` by default. Anything that makes something live (`ACTIVE`), changes
a budget or archives (`ARCHIVED`) requires `confirm: true`. Without confirmation
you only get a preview, and nothing is sent to Meta.

| Tool | What it does | Requires confirmation? |
| - | - | - |
| `create_campaign` | Creates a new campaign | Only if the status is ACTIVE or ARCHIVED (if paused, it is created immediately) |
| `create_ad_set` | Creates an ad set with budget, targeting and optimization goal | Only if ACTIVE or ARCHIVED |
| `create_ad` | Creates an ad from an existing creative | Only if ACTIVE or ARCHIVED |
| `update_status` | Sets campaign/ad set/ad to PAUSED, ACTIVE or ARCHIVED | Yes for ACTIVE and ARCHIVED; PAUSED is carried out immediately |
| `update_budget` | Changes the daily or lifetime budget | Always |

On a connection that is locked to one ad account, `update_status` and
`update_budget` are hidden. See the section on locking below.

> **[Building on top yourself? See the API reference](https://docs.consile.ai/developers/tools/meta-ads.md)**
>
> Full reference with arguments, pagination, filters, guardrail fields and
> return values for each tool.

## How the guardrail works

The safety is built into the connector itself:

1. **Everything new is created paused.** A new campaign, ad set or ad
   is `PAUSED` by default and spends no money until you ask for it.
2. **Going live, budget changes and archiving require `confirm: true`.** Making
   something live (`ACTIVE`), changing a budget or archiving requires your AI to send an
   explicit confirmation. Without it, you get a structured preview of
   exactly what would happen, and no call is sent to Meta. A bid can only be
   set when an ad set is created (`bidAmountMinor`); there is no tool
   for changing a bid afterwards.
3. **No deleting.** Removal only happens by archiving (status
   `ARCHIVED`), and it requires confirmation.

The write tools are marked as modifying to your AI client, so clients
like Claude can ask for your permission before they run.

> [!TIP]
>
> How preview and confirmation work across all
> write connectors is described under
> [Actions & guardrails](https://docs.consile.ai/en/essentials/actions-and-guardrails.md).

## Try asking

> **Performance & reporting**
>
> > *"Show the account's performance for the last 30 days: spend, clicks, CTR and CPC."*
>
> > *"Which campaigns had the best cost per lead last month?"*
>
> > *"Break the last 14 days down by gender and age."*

> **Creatives & video**
>
> > *"What do my best-performing ads say, and what do they link to?"*
>
> > *"Which image and headline variant drives the most results in the dynamic ad?"*
>
> > *"How many watch the video all the way to ThruPlay?"*

> **Audiences & planning**
>
> > *"How large an audience can I reach in Denmark among 18-35-year-olds interested in running?"*
>
> > *"Which custom audiences exist on the account, and roughly how large are they?"*

> **Leads**
>
> > *"How many leads has my latest Lead Ads form captured?"*
>
> > *"Show the newest leads with name and email."*

> **Create & manage (guardrailed)**
>
> > *"Create a campaign 'Spring 2026' with the objective OUTCOME\_LEADS, and leave it paused."*
>
> > *"Raise the budget on ad set 1234 to 200 DKK a day."* (you are asked to confirm)
>
> > *"Activate campaign 5678."* (you get a preview and must confirm before it starts spending)

> [!TIP]
>
> Mention a date range (or for example "last 7 days") and an ad account in
> the question, so you get a precise answer right away. Budgets are given in the
> currency's smallest unit, for example øre (20000 = 200.00 DKK).

## Lock to one company

A Meta login can reach several ad accounts. An administrator can lock an agreement to one
ad account, so every call on that agreement keeps to it. The lock is optional.
Without a lock, the connection works as before, and all 39 tools are there.

On a locked connection:

* `list_ad_accounts` only shows the locked ad account.
* The tools still need the ad account (`adAccountId`), and it must be
  the locked one. If your AI names another account, the call is refused, and your AI is
  told which account the connection is locked to.
* `list_ad_sets`, `list_ads`, `campaign_insights`, `ad_set_insights` and
  `ad_insights` cannot be limited to one campaign, one ad set or one ad.
  They answer for the whole ad account with one row per campaign, ad set or
  ad.
* `create_campaign`, `create_ad_set` and `create_ad` work as before and
  always create in the locked ad account.
* 11 tools cannot be limited to one ad account. They are hidden, so your AI does not
  see them and cannot call them. 28 tools are left.

| Hidden tool | What it means for your AI |
| - | - |
| `update_status`, `update_budget` | It cannot make anything live, pause it, archive it or change a budget |
| `list_pages`, `list_lead_forms`, `list_leads`, `get_lead` | It cannot read Facebook Pages, lead forms or leads |
| `get_ad_creative`, `get_ad_creative_asset_feed_spec`, `get_ad_preview`, `creative_asset_insights_breakdown` | It cannot look up one creative, show a preview or read the variants in a dynamic ad. `list_creatives` and `list_ad_creatives_detail` still work |
| `query` | It cannot use the advanced reading |

If an administrator connects the agreement again with **Reconnect** or a link from your
AI, all calls are refused until an administrator has chosen the ad account again.
If an administrator disconnects, the lock disappears. An ad account can only
be locked on one agreement at a time. How to lock, and what else happens:
[Lock a connection to one company](https://docs.consile.ai/en/portal/company-lock.md).

## Limitations

* **Writing is guardrailed, not unrestricted.** The five write tools can create and
  manage campaigns, but only behind the confirmation barrier above. See
  [Actions & guardrails](https://docs.consile.ai/en/essentials/actions-and-guardrails.md).
* **No fixed access levels.** Meta Ads does not have the **Read only** level.
  A user with **All tools** under **Team** gets all the tools the
  organization has switched on, including the five write tools. If a user should only
  have some of them, for example only the read tools, an administrator chooses
  **Custom**. See [Custom access](https://docs.consile.ai/en/portal/team.md#custom-access).
* **No deleting.** Objects can only be archived, not deleted permanently.
* **Bids can only be set on creation.** A bid cap (`bidAmountMinor`) can be
  given when an ad set is created, but the connector cannot change bids
  afterwards. You do that in Ads Manager.
* **Creatives are not built from scratch.** Ads are created from an *existing*
  creative (from `list_creatives`); uploading images/video is not supported in
  this version.
* **Audiences are metadata only.** Custom Audiences never return members.
  Meta only stores hashes.
* **Errors from Meta are not shown verbatim.** If Meta refuses a call, for example an invalid
  audience spec, your AI only gets the message `Tool invocation failed.` without Meta's
  explanation. If only one write call fails, check the values (objective, optimization,
  budget, audience) in Ads Manager. If all calls fail, connect Meta Ads again.
* **Reconnect about every 60 days.** Access to Meta usually expires after
  about 60 days. If it has expired, your AI gets a message that Meta Ads must be connected
  again. If you have revoked access at Meta, you also have to reconnect.
  The **Connected** status in the portal shows that access is stored, not that
  it still works. Only an administrator can reconnect. If the agreement is locked, the
  ad account must be chosen again afterwards. How to reconnect: see
  [Connect Meta Ads](https://docs.consile.ai/en/connect/connect-meta-ads.md).

Is something not working as expected? See [Troubleshooting](https://docs.consile.ai/en/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.