---
title: "Meta Ads MCP: Ad Library tools, parameters and limits"
description: "How Proxy's Meta Ads MCP reads the Facebook and Instagram Ad Library: every parameter, accepted values, paging, cursors, credit cost and failure modes."
---

> For AI agents: the full docs index is at [https://useproxy.dev/docs/llms.txt](https://useproxy.dev/docs/llms.txt). Append `.md` to any docs URL for Markdown.

There are two kinds of Meta Ads MCP. One manages your own ad account. Proxy is the other kind: it reads the public Meta Ad Library, so an assistant can pull any brand's Facebook and Instagram ads. It is read-only and never connects to an ad account.

This page documents exactly how the three Meta tools behave. For the short parameter tables, see the [Meta tool reference](https://useproxy.dev/docs/tools/meta-ads).

## Connect

One endpoint serves every client and every platform:

```text
https://mcp.useproxy.dev/mcp?ref=docs
```

Sign-in is OAuth, with no API keys. Steps per client are in [Connect your client](https://useproxy.dev/docs/clients), with deeper notes for [Claude](https://useproxy.dev/docs/ads-mcp-claude), [ChatGPT](https://useproxy.dev/docs/ads-mcp-chatgpt) and [Claude Code](https://useproxy.dev/docs/ads-mcp-claude-code).

## Which tool fires when

| You ask for | Tool chain |
| --- | --- |
| A brand's current ads | `get_meta_ads` with the brand name |
| A brand with an ambiguous name | `get_meta_platform_id`, then `get_meta_ads` with the chosen `page_id` |
| Ads about a topic, no brand known | `search_meta_ads_by_keyword` |
| Creator or partnership ads for a brand | `search_meta_ads_by_keyword` with the brand handle, domain or hashtag |
| A transcript or visual breakdown | `analyze_ad_video` or `analyze_ad_image` with the `ad_id` |

`get_meta_ads` accepts brand names directly. A name that is not all digits is resolved to its top-ranked page, so the lookup step is only needed when you want to choose between pages.

## get_meta_platform_id

Finds the Meta pages that match a brand.

| Parameter | Type | Behaviour |
| --- | --- | --- |
| `brand_names` | string or list | One name, or a list looked up in parallel |

- Returns up to three candidates per brand: `page_id`, `name`, `verification`, `ig_followers`, `image_uri`.
- Candidates are ranked by how closely the page name matches the query, then by Instagram followers, with verification as the tiebreak. Deleted pages are dropped.
- In a list call, a brand whose lookup failed is reported as failed, not as "no such brand".
- Zero matches returns a hint to retry with the bare brand name, without a country, city or legal suffix.

## get_meta_ads

Pulls a page's ads.

| Parameter | Default | Accepted values and behaviour |
| --- | --- | --- |
| `platform_ids` | required | Page ID, brand name, or a list of either |
| `limit` | 30 | Per page ID. Values under 25 are raised to 25; the maximum is 1000 |
| `country` | all | Two-letter code such as `US`. Anything else is rejected |
| `status` | `active` | `active`, `inactive` or `all`. Becomes `all` when a date is set |
| `active_only` | false | Only ads still running |
| `media_type` | `all` | `all`, `image` or `video`. `image` includes carousels |
| `sort_by` | longest-running first | `longest_running`, `newest`, `total_impressions`, `relevancy_monthly_grouped` |
| `min_duration_days` | none | Only ads that have run at least this long |
| `language` | none | Two-letter code such as `EN` |
| `start_date`, `end_date` | none | `YYYY-MM-DD`, filters by impression dates |
| `include_reach` | false | Adds per-ad EU and UK reach where Meta discloses it |
| `trim` | true | `false` adds funding entity, disclaimer, languages and positions |
| `cursor` | none | Continuation token from the previous response |

Notes on the values:

- **`sort_by` aliases.** `impressions` is read as `total_impressions`, `longest` and `oldest` as `longest_running`, `recent` and `latest` as `newest`. Any other value returns an error that lists the four valid ones.
- **`longest_running` and `newest` rank only the ads fetched.** They are applied after the fetch, not by Meta. Raise `limit` or set `min_duration_days` for a wider net.
- **`media_type` aliases.** `static`, `photo`, `meme`, `carousel`, `dco` and `dpa` are read as `image`. Unknown values return an error instead of silently returning everything.
- **Dates imply history.** With `start_date` or `end_date` and no explicit `status`, the search covers all statuses.

### What each ad contains

Every row carries `ad_id`, `page_id`, `page_name`, `advertiser_name`, `advertiser_handle`, `media_type`, `headline`, `body`, `cta_text`, `link_url`, `placements`, `start_date`, `end_date`, `is_active` and `ad_snapshot_url`.

- `media_type` is `IMAGE`, `VIDEO`, `DCO` (any carousel or dynamic creative) or `TEXT`.
- `headline` can be empty on video ads. Use `body` and `media_type`.
- `is_active` is derived from `end_date`, the last day the ad was shown.
- Ads that share one creative are collapsed into one row. `ads_in_creative` says how many ads run that creative.
- `reach`, `reach_by_age_gender`, `impressions` and `spend` appear only when Meta's transparency data discloses them for that ad. A missing field means not disclosed, not zero.

The response also carries `has_active_ads`, `count`, `estimated_total_count`, a one-line profile of the fetched set (format mix, placements, longest-running ad, launches in the last 30 days) and, in list calls, a per-brand outcome.

:::note
Rows do not include a media URL. Meta's media URLs are signed and expire, so the analysis tools take the stable `ad_id` and fetch a fresh file themselves.
:::

### What it never contains

- Spend, clicks, CPC or results for ordinary commercial ads. Meta does not publish them.
- Ads a brand paid a creator to run from the creator's own page. Those sit under the creator's page.
- Old commercial ads. Meta keeps them for about a year after they stop; political and issue ads are kept for seven years.

## search_meta_ads_by_keyword

Searches every advertiser by topic.

| Parameter | Default | Accepted values and behaviour |
| --- | --- | --- |
| `query` | required | Keyword, phrase, handle, domain or hashtag |
| `limit` | 30 | One upstream page. Maximum 1000, capped at 10 pages |
| `sort_by` | `relevancy_monthly_grouped` | Same four values as `get_meta_ads` |
| `search_type` | `keyword_unordered` | Or `keyword_exact_phrase` for multi-word product names |
| `ad_type` | `all` | Or `political_and_issue_ads` |
| `min_duration_days` | none | Scans up to 5 pages for ads that have run this long |
| `country`, `media_type`, `start_date`, `end_date`, `trim`, `cursor` | | Same as `get_meta_ads` |
| `status` | `ACTIVE` | `ACTIVE`, `INACTIVE` or `ALL`. Becomes `ALL` when a date is set |

- **The default sort only returns recent ads.** `relevancy_monthly_grouped` stays on topic but covers roughly the last month. Combining it with `min_duration_days` returns an error, because nothing would match.
- **With `min_duration_days` and no `sort_by`, the sort switches to `total_impressions`,** which covers ads of any age but matches more loosely.
- **Relevance is reported.** The response includes `query_hit_count`, the number of returned ads whose own copy mentions a query word. When five or more ads come back and under 30% mention it, the result is flagged `off_topic` and the assistant is told to say so.
- Without `country`, results span all countries.

## Paging and cursors

- **Upstream page size.** The first page of a brand's ads holds 30 ads; every later page holds 10.
- **Windows.** A large result is returned in windows of about 40,000 characters. The rest is stored for 24 hours and read with a cursor of the form `rs:<id>:<offset>`. Reading it costs no credits.
- **Upstream cursors.** Any other cursor value continues the scan at Meta. It works with a single page ID only and costs credits, so the assistant is told to ask before continuing.
- **Expired cursor.** After 24 hours an `rs:` cursor returns an error asking to re-run the call without a cursor.

## Credit cost

| Call | Credits |
| --- | --- |
| `get_meta_platform_id` | 1 per brand |
| `get_meta_ads`, default `limit` 30 | 1 per page ID, plus 1 per brand name that had to be resolved |
| `get_meta_ads`, larger `limit` | 1 for the first 30 ads, then 1 per 10 more. `limit` 150 is 13 |
| `get_meta_ads` with `media_type` `image` | Up to 5, because image mode scans five unfiltered pages |
| `get_meta_ads` with `min_duration_days` or `active_only` | Up to 5, so sparse matches are not reported as zero |
| `get_meta_ads` with a list | Per brand, capped at 10 pages each |
| `search_meta_ads_by_keyword` | 1 per page: 1 by default, up to 5 with `min_duration_days` |
| Reading an `rs:` cursor | 0 |
| `analyze_ad_image`, `analyze_ad_video` | 1 per ad |

Free is 20 credits a day with no card, Pro is $50 a month for 100 a day, and Max is $100 a month for 250 a day. There is no overage billing. See [Credits and plans](https://useproxy.dev/docs/credits).

## Failure modes

| Situation | What the tool returns |
| --- | --- |
| Page runs ads, but none match the filters | Zero ads with `has_active_ads` true and a note to loosen the filters |
| Page has no ads | Zero ads with `may_be_inactive` true and a note to try another candidate page |
| Empty date window | A note that the library may no longer hold that period |
| One brand in a list fails | That brand is marked "fetch failed, not confirmed inactive"; the others still return |
| Meta fails mid-scan | The ads fetched so far, plus a cursor to resume |
| Credits run out mid-scan | The ads fetched so far; unfetched brands are marked as not fetched |
| Several parallel single-brand calls | An error asking for one call with a list of IDs |
| Rate limit, timeout or outage | A short retry hint. Raw upstream errors are never passed through |
| Mistyped `ad_id` in an analysis call | "Meta's Ad Library has no ad with ID ..." |

## Worked prompts

```text
What Meta ads is [brand] running right now? Show the 30 longest-running.
```

`get_meta_ads` with the brand name. 2 credits: one to resolve the name, one page of ads.

```text
[brand] is ambiguous. List the candidate Meta pages and pull ads from the one whose site is [domain].
```

`get_meta_platform_id`, then `get_meta_ads` with that `page_id`. 2 credits.

```text
Compare the video ads of [brand A], [brand B] and [brand C] in the US.
```

One `get_meta_ads` call with a list of three names, `media_type` `video`, `country` `US`. 6 credits.

```text
Search Meta for "collagen gummies" ads that have run at least 90 days and list the hooks that repeat.
```

`search_meta_ads_by_keyword` with `min_duration_days` 90. Sort switches to `total_impressions`. Up to 5 credits.

```text
Transcribe [brand]'s longest-running video ad and break down the first three seconds.
```

`get_meta_ads`, then `analyze_ad_video` with that ad's `ad_id` as `ad_archive_id`. 3 credits.

## Guides

- [How to set up a Meta Ads MCP](https://useproxy.dev/blog/meta-ads-mcp)
- [How to use the Facebook Ad Library](https://useproxy.dev/blog/how-to-use-facebook-ad-library)
- [Meta Ad Library API alternatives](https://useproxy.dev/blog/meta-ad-library-api-alternative)
