Meta Ad Library tools
Find a brand on Facebook and Instagram, pull its active ads, or search the whole Meta Ad Library by keyword.
get_meta_platform_id
Search the Meta Ad Library for a brand and return ranked candidate pages.
| Parameter | Type | Notes |
|---|---|---|
brand_names |
string or string[] | One brand or a batch |
Returns up to three candidates per brand, verified pages first, then by follower count. Each candidate carries page_id, page_name, image_uri and a may_be_inactive flag so the assistant can try the next one if a page returns no ads.
get_meta_ads
Retrieve currently running ads for one or more Meta page IDs.
| Parameter | Type | Notes |
|---|---|---|
platform_ids |
string or string[] | From get_meta_platform_id |
limit |
int | Default 100 |
country |
string | ISO country code |
active_only |
bool | Only ads still running |
sort_by |
string | total_impressions or relevancy_monthly_grouped |
status, media_type |
string | Case-insensitive filters |
start_date, end_date |
string | ISO dates |
min_duration_days |
int | Long-running ads only |
include_reach |
bool | Enrich with EU reach where available |
trim |
bool | Default true; false returns full metadata |
Each ad includes ad_id, page_id, body text, media_type, media_url, start and end dates, and an ad_url into the public library. For a transcript, pass the ad’s ad_id as ad_archive_id, together with page_id, to analyze_ad_video.
search_meta_ads_by_keyword
Search across all advertisers without knowing the brand.
| Parameter | Type | Notes |
|---|---|---|
query |
string | Keyword, phrase, handle, domain or hashtag |
limit |
int | Default 100 |
sort_by |
string | Same vocabulary as get_meta_ads |
country, status, media_type |
string | Filters |
start_date, end_date |
string | ISO dates |
Credits
One credit per call. Batch calls cost one credit per item.