Search Meta ads by keyword | Meta Ads API

Searches the public Meta Ad Library (Facebook and Instagram ads) for required q. Filter by country, delivery status, ad type, media type, dates, language, platform, advertiser page, and reach. Use cursor to page; page_size is 1-50.

1 credit / requestBilled only on success

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Query Parameters

q*string

Search keyword, phrase, or advertiser name.

Length1 <= length

country?string

ISO 3166-1 alpha-2 country code. Examples: IN, US, GB, DE.

Length2 <= length <= 2

active_status?string

Ad delivery status. all = active and inactive ads, active = currently running ads, inactive = stopped ads.

Value in

"all"
"active"
"inactive"

ad_type?string

Ad category. ALL includes all ad types; other values narrow results to the selected category.

Value in

"ALL"
"POLITICAL_AND_ISSUE_ADS"
"HOUSING_ADS"
"EMPLOYMENT_ADS"
"CREDIT_ADS"

search_type?string

Query match mode. keyword_unordered matches all words in any order; keyword_exact_phrase matches the exact phrase.

Value in

"keyword_unordered"
"keyword_exact_phrase"

media_type?string

Creative format filter. all = every format, image = static images, video = videos, meme = image/text meme-style creatives.

Value in

"all"
"image"
"video"
"meme"

sort_mode?"total_impressions"

Sort by total impressions.

Value in

"total_impressions"

sort_direction?"desc"

Sort direction. Use with sort_mode.

Value in

"desc"

cursor?string

Pass pageInfo.cursor from the previous response to get the next page. Omit for the first page.

page_size?integer

Number of ads to return per request. Accepted range: 1-50.

Range1 <= value <= 50

date_min?string

Start Date in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$

date_max?string

End Date in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$

content_languages?string

Comma-separated ISO 639-1 language codes, for example en,hi.

publisher_platforms?string

Comma-separated platforms. Accepted values: FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER.

page_ids?string

Comma-separated page IDs to limit results to selected advertisers.

is_targeted_country?boolean

When true, only return ads targeted to the selected country.

potential_reach_min?|

Minimum estimated audience size.

Range0 <= value

potential_reach_max?|

Maximum estimated audience size.

Range0 <= value

curl -X GET "https://example.com/v1/meta/search?q=flipkart" \  -H "x-api-key: YOUR_API_KEY"

{  "data": {    "items": [      {        "ad_archive_id": "string",        "page_id": "string",        "property1": null,        "property2": null      }    ],    "pageInfo": {      "cursor": "string",      "hasNextPage": true    }  }}