For AI agents: the full docs index is at /docs/llms.txt. Append .md to any docs URL for Markdown.
Skip to content
Proxy Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Meta Ads MCP: Ad Library tools, parameters and limits

How Proxy's Meta Ads MCP reads the Facebook and Instagram Ad Library: every parameter, accepted values, paging, cursors, credit cost and failure modes.

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.

Connect

One endpoint serves every client and every platform:

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

Sign-in is OAuth, with no API keys. Steps per client are in Connect your client, with deeper notes for Claude, ChatGPT and 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.

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.

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

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.

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

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.

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.

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

Was this page helpful?