Search the Ad Library
Search Meta's Ad Library for other advertisers' ads, by keywords, a brand name, or one page's ads, and get each ad's page, copy, call to action, start date and image urls.
Tool name: search-ad-library.
Search Meta's Ad Library for other advertisers' ads, by keywords, a brand name, or one page's ads, and get each ad's page, copy, call to action, start date and image urls. Read-only. Use the image urls as references in generate-creatives, for layout and style only: never copy another brand's name, logo, product or claims.
When to use
Find reference ads before making images: what competitors or a niche are running, or a specific brand the user names. Offer it when the user has no references of their own. Searches can take up to a minute.
Access
| Property | Value |
|---|---|
| Required scope | read |
| Publishes | No |
| Read-only | Yes |
| Destructive | No |
| Idempotent | Yes |
| Open world | Yes |
Input
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | An advertiser's website domain, such as "triplewhale.com", to get that advertiser's own ads; a name also brings other advertisers' ads. Or keywords for an offer. With pageId, * lists every ad of that page. At most 200 characters. |
pageId | string | No | One Facebook page id, from an earlier result, to see only that advertiser's ads. |
country | string | No | Two-letter country the ads ran in. Defaults to US. |
activeOnly | boolean | No | Only ads running now. Defaults to true; an ad that has run for months is usually a winner. |
limit | integer | No | Ads per page, 1-24. Defaults to 12. Minimum 1, maximum 24. |
cursor | string | No | nextCursor from the previous page. At most 500 characters. |
forRound | boolean | No | true when you search for references for a round of ads you are making: the user does not see the results. Omit it when the user asked to see other advertisers' ads. |
Output
| Field | Type | Required | Description |
|---|---|---|---|
ads | object[] | Yes | |
withoutImages | integer | Yes | Ads on this page that carried no image, and are left out. |
nextCursor | string | null | Yes |
REST equivalent
GET /v1/brands/{brandId}/ad-library/ads, Search the Ad Library. CLI: koast search-ad-library.