Get Meta Ad Library Ads
get_meta_adsUse this to see what ads a brand is currently running on Meta — pass Meta Platform ID(s) or brand name(s) (a name resolves to its top-ranked page, so no get_meta_platform_id call is needed). Returns ad content, dates, and targeting info; set include_reach=true for reach and age/gender/country delivery demographics. ALWAYS pass platform_ids as a list when researching multiple brands — e.g. platform_ids=['123','456','789'] — never call this tool multiple times in parallel for different IDs (parallel calls are rate-limited server-side and will fail). Look up media_url in the media_urls dict by ad_id before calling analyze_ad_image/analyze_ad_video. If may_be_inactive: true, the page likely paused advertising — try other candidate IDs. Note: headline may be null on video ads; use body + media_type instead. Set min_duration_days: 7 to return only ads active for 7+ days. Set active_only: true to return only currently running ads. Set status='inactive' to see retired creatives. Optionally sort with sort_by='total_impressions' (highest-spend first) or 'relevancy_monthly_grouped'. If comparing multiple brands or surfacing patterns across ads, follow up with get_competitive_brief. SHOWING THE ADS — REQUIRED: don't just summarise in text — you MUST call show_ad_carousel at least once this turn so the user SEES the creatives as visual proof, not only reads about them. Interleave it WITH your analysis: each time you make a point about specific ads, call show_ad_carousel right after that sentence with only the ads that evidence THAT point (pass each as {ad_id, page_id} copied from this tool's output; the server fills in copy/media/cards). Make as many carousels as you have distinct points, strictly point → its carousel → next point → its carousel; NEVER stack carousels back-to-back or dump all points as a list after the carousels. Be generous: across your carousels, show MOST of the ads this tool returned (up to 20 per carousel) — skip only ads that are irrelevant or near-duplicates. Never render just 2-3 ads when a dozen were found; if discussed points don't cover all the ads, close with a broader carousel of the rest. Don't finish a turn that discusses specific ads without having rendered at least one. You may mix Meta {ad_id, page_id}, Google {ad_url}, LinkedIn {linkedin_id}, and TikTok {tiktok_id} refs in a single carousel when a point spans platforms. The only time to skip it entirely is when this tool returned zero ads.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| trim | No | True (default) returns essential fields; False adds full metadata including targeting. | |
| limit | No | Max ads per platform ID (default 30, max 1000), fetched in 30-ad pages at 1 credit each. Raise it only for an exhaustive audit; the response cursor fetches the next page. | |
| cursor | No | Continuation token from a previous response. Present when more ads exist beyond what was scanned. Single platform ID only; offer to continue before spending extra credits. | |
| status | No | "active" (default), "inactive" or "all". | |
| context | No | One plain sentence, 8-20 words, starting with a verb, stating what the user is trying to accomplish in this conversation. Name the brand, competitor, industry, or topic involved. Reuse the exact same sentence on every tool call in this conversation. Never include people's names, emails, phone numbers, credentials, or internal company details. Never describe this tool or why it was chosen. Example: 'Compare Notion and Coda Meta ads to find hooks for a productivity app launch.' | |
| country | No | Two-letter country code to filter by targeting, e.g. "US". Default: all countries. | |
| sort_by | No | "total_impressions" (highest spend first) or "relevancy_monthly_grouped". | |
| end_date | No | Filter by impressions end date, YYYY-MM-DD. | |
| language | No | Two-letter language code, e.g. "EN" or "FR". | |
| media_type | No | "all" (default), "image" (static creatives, including image carousels) or "video" (video only). | |
| start_date | No | Filter by impressions start date, YYYY-MM-DD. | |
| active_only | No | True returns only currently running ads. | |
| platform_ids | Yes | Meta Platform ID(s) from get_meta_platform_id, or brand name(s) like "Nike" (resolved to the top-ranked page, 1 extra credit per name). For several brands pass one list (a single batched call); parallel single-ID calls are throttled. | |
| include_reach | No | True adds each ad's EU/UK reach and age/gender/country breakdowns (one upstream call per ad). Suited to reach, audience and performance questions. | |
| conversation_id | No | Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. | |
| min_duration_days | No | Only ads that have run for at least this many days. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _mcp_instructions | No | Server-issued metadata for this conversation. |