---
title: "Meta Ad Library tools"
description: "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](/docs/tools/analysis#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 |

:::tip
For creator partnership ads, search the brand handle, domain or a partner hashtag. Coverage is best-effort because Meta does not label paid partnerships in the library.
:::

## Credits

One credit per call. Batch calls cost one credit per item.