ToolzerHub Docs

Search Meta ads by keyword (v1)

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-10.

1 credit / requestBilled only on success
GET
/v1/meta/search

Authorization

ApiKeyAuth
x-api-key<token>

In: header

Query Parameters

q*string

Search keyword, phrase, advertiser name, or numeric ad ID.

Length1 <= length
country?string

ISO 3166-1 alpha-2 country code, or ALL for every country. Defaults to ALL. Examples: US, GB, IN, ALL.

Match^(?:[a-z]{2}|all)$/i
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?|

Ads per request, 1-10 (Meta's own page size). Larger values are treated as 10. Use cursor for more.

Range1 <= value <= 10
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.

Match^\s*\d+(\s*,\s*\d+)*\s*,?\s*$
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    }  },  "details": {    "reason": "no_results",    "message": "string"  }}