Find advertisers by name
Advertisers matching a brand or page name, with page id, alias, category, verification, ad count and follower count — the page id is what the advertiser routes take. includeProfiles fills in details the search alone leaves empty.
/search-advertisers Advertisers https://api.fetchlayer.dev/facebook-ad-library/search-advertisers Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
query string required Advertiser or brand name to look up.
country string optional Two-letter country code, or ALL. (default: ALL)
adType string optional Only advertisers with matching ads of this type: ALL, POLITICAL_AND_ISSUE_ADS (POLITICAL is accepted for it), HOUSING_ADS, EMPLOYMENT_ADS or FINANCIAL_PRODUCTS_AND_SERVICES_ADS (CREDIT_ADS is its earlier name). Case-insensitive. Any type but ALL leaves out name suggestions, which carry no ad type; for the special ad categories the list comes from the first page of matching ads, and a note says it may be incomplete. (default: ALL)
limit integer optional Maximum advertisers returned (max 500), or -1 for everything available. (default: 30)
matches string optional "all" (default): advertisers named like the query and advertisers whose ads match it, ranked together. "name": only the Pages Facebook’s own name search suggests, in its order (up to about 15), with ad-content matches left out before limit is applied; adCount is null for these. With any adType but ALL, name is a 400. Case-insensitive; any other value is a 400. (default: all)
includeProfiles boolean optional Also fill in page details — alias, verification, category, likes and profile picture — for advertisers the search alone returns without them, up to 30 per request. Adds a few seconds. Whatever it cannot fill, the note names advertiser by advertiser and says why: no public profile, a lookup that failed (asking again may fill it), or time ran out. (default: false)
format string optional json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON. (default: json)
timeoutMs integer optional Time limit for the whole request, in milliseconds (1000–120000), counted from its arrival, time spent waiting in the queue included; a value outside that range is a 400. When it runs out, a paged request returns what it has with nextCursor and a note, billed for the pages it delivered; a request with nothing to return yet fails with a 503 you can retry, marked with the response header X-Timeout-Source: caller. Left out, the request runs as long as it needs.
Response Fields
search-advertisers
Find advertisers by name
advertisers object[] Matching advertiser pages: those named like the query first (an exact name, then names starting with it, then names containing it), then others whose ads match it. The Ad Library’s own name suggestions (up to 15) are included, so a page named like the query is listed even when none of its ads match. Some can come without page details or verification; the note says how many, and includeProfiles fills them in. A detail that is not known is null, or [], never left out. Under a tight timeoutMs the response may come back without the advertisers found through their ads, with a note saying so, rather than as a 503.
advertisers[].pageId string Page id — the handle for advertiser-ads and advertiser-profile.
advertisers[].pageName string Public page name.
advertisers[].adCount integer | null How many ads the page is running, or null — not 0 — for a suggestion with no matching ads found.
advertisers[].source string index (in the Ad Library’s advertiser list for the query), ads (found only among the matching ads) or suggestion (named like the query, with no matching ads found).
advertisers[].pageCategories string[] Categories the page lists itself under.
advertisers[].pageLikeCount integer | null Follower count on the page.
advertisers[].pageProfilePictureUrl string | null The page’s profile picture, or null when not known — includeProfiles fills it in.
advertisers[].instagramUsername string | null The page’s Instagram username; null when it links none or it is not known here — instagramUsernameStatus says which. Advertisers named like the query, and every one includeProfiles fills in, come with it.
advertisers[].instagramUsernameStatus string found: instagramUsername is the account’s username. not-published: the page’s own details link no Instagram account. not-looked-up: not known here — an ad names an Instagram account only when it is shown under one, so null says nothing about whether there is one; includeProfiles fills it in, as do ad-detail for the advertiser and advertiser-profile (as igUsername). With includeProfiles: lookup-failed (no answer for this account this time; asking again may fill it), skipped-cap (past the 30 accounts filled per request) or skipped-time (not filled in the time available). A username that cannot be filled never fails the request.
advertisers[].pageAlias string | null The page’s facebook.com/<alias> username, or null for a page without one.
advertisers[].pageCategory string | null The page’s main category.
advertisers[].pageVerification string | null BLUE_VERIFIED, NOT_VERIFIED and so on, or null when not known — includeProfiles fills it in.
advertisers[].pageIsDeleted boolean Whether the page has been deleted.
advertisers[].detailsStatus string Whether verification, category and profile picture are all present, and if not, why. complete: all present. not-published: Facebook publishes no more for this page; asking again will not fill it. lookup-failed: no answer this time; asking again may fill it. skipped-time: time ran out first; asking again, or for fewer advertisers, may fill it. skipped-cap: past the 30 advertisers a request fills in. not-requested: details missing and includeProfiles was not set.
advertiserCount integer Number of advertisers in this response.
derivedFromAds boolean True when any result was found among the matching ads.
matches string The mode the search ran in: all or name. With name, every advertiser has source suggestion and adCount null; a query with no suggested Pages returns an empty list with a note, with no fallback to ad matches. A Page that only appears through its ads, such as an Instagram-only advertiser, is found only with all.
Request
curl -X POST "https://api.fetchlayer.dev/facebook-ad-library/search-advertisers" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"query":"Nike","country":"US","limit":10}'Response
{
"advertiserCount": 2,
"advertisers": [
{
"pageId": "15087023444",
"pageName": "Nike",
"adCount": 42,
"pageLikeCount": 39503345,
"pageAlias": "nike",
"pageCategory": "Sportswear",
"pageVerification": "BLUE_VERIFIED",
"pageIsDeleted": false
}
]
}