Insight Social
GET /v1/facebook/adlibrary/company/ads

Facebook Ad Library Company Ads API

Returns the ads one company or page is running in the Facebook Ad Library, each with its creative, status, spend, and targeting info.

Get a free API keyFull API reference

50–350 credits, metered · cursor pagination · failed calls free · 10 free calls to start

curl "https://api.insightsocial.app/v1/facebook/adlibrary/company/ads?companyName=Lululemon" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY"
200 OKJSON
{
"success": true,
"platform": "facebook",
"endpoint": "/v1/facebook/adlibrary/company/ads",
"schema_version": "2",
"data": {
"items": [
{
"post": {
"id": "<string>",
"url": "<string | null>",
"kind": "<string | null>",
"content": {
"text": "<string | null>",
"media_urls": "<array | null>",
"thumbnail_url": "<string | null>",
"duration_seconds": "<number | null>"
},
"author": {
"id": "<string | null>",
"username": "<string | null>",
"display_name": "<string | null>",
"avatar_url": "<string | null>",
"verified": "<boolean | null>"
},
"engagement": {
"views": "<integer | null>",
"likes": "<integer | null>",
"comments": "<integer | null>",
"shares": "<integer | null>",
"saves": "<integer | null>"
},
"flags": {
"nsfw": "<boolean | null>",
"spoiler": "<boolean | null>",
"pinned": "<boolean | null>",
"deleted": "<boolean>",
"likes_hidden": "<boolean | null>",
"comments_hidden": "<boolean | null>",
"shares_hidden": "<boolean | null>",
"views_hidden": "<boolean | null>",
"saves_hidden": "<boolean | null>"
},
"published_at": "<string | null>",
"language": "<string | null>",
"ext": "<object | null>"
}
}
]
},
"pagination": {
"next_cursor": "<string | null>",
"has_more": "<boolean>"
},
"unavailable": [],
"credits_used": "<integer>"
}

When to use it

Use it when you know the advertiser by pageId or company name; to find ads by keyword across advertisers, use adlibrary/search/ads.

Parameters

Query parameters for GET /v1/facebook/adlibrary/company/ads. Send your key in the x-api-key header.

NameRequiredDescription
pageIdOne of pageId, companyNameFacebook page ID of the advertiser.
companyNameOne of companyName, pageIdThe name of the company. Can either use this or pageId.
countryNoThis can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
statusNoStatus of the ad. Defaults to ACTIVE.
media_typeNoMedia type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.
languageNoLanguage to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc
sort_byNoSort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
start_dateNoStart date to search for. Format: YYYY-MM-DD
end_dateNoEnd date to search for. Format: YYYY-MM-DD
cursorNoCursor to paginate through results
trimNoSet to true for a trimmed down version of the response
includeNoSet to audience (one token only) to fill, on every ad that ran in the EU, post.ext.ad.eu_total_reach, post.ext.ad.eu_reach_breakdown (reach per EU country by age band and gender), post.ext.ad.targets_eu, target_ages, target_gender and target_locations. Without it the call is unchanged.

Response fields

The same unified schema every platform returns, so code written for Facebook works on the other eight. A field the platform did not provide is null and listed in unavailable.

FieldTypeNotes
idstringAn identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.
urlstring | null
kindstring | nullThe format of the post. Format words only, never a platform name. short = short-form vertical video (a reel, a TikTok, a YouTube Short).
content.textstring | null
content.media_urlsarray | null
content.thumbnail_urlstring | null
content.duration_secondsnumber | null
author.idstring | null
author.usernamestring | null
author.display_namestring | null
author.avatar_urlstring | null
author.verifiedboolean | null
engagement.viewsinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.likesinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.commentsinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.sharesinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.savesinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
flags.nsfwboolean | null
flags.spoilerboolean | null
flags.pinnedboolean | null
flags.deletedboolean
flags.likes_hiddenboolean | null
flags.comments_hiddenboolean | null
flags.shares_hiddenboolean | null
flags.views_hiddenboolean | null
flags.saves_hiddenboolean | null
published_atstring | nullISO-8601 timestamp in UTC, ending in Z.
languagestring | nullThe content's language as the platform states it, e.g. en, pt-BR. Detected languages come later (§7.1).
extobject | nullPlatform-specific fields, snake_case.

Every field, error and example is in the Facebook Ad Library Company Ads API reference.

How much does the Facebook Ad Library Company Ads API cost?

Metered: 50–350 credits a call. The ceiling is reserved when the call starts and you are charged what it actually read.

  • Failed calls are free

    A call that errors or finds nothing costs 0 credits.

  • Know the price first

    Add dry_run=1 and the response quotes the call without making it. Nothing is charged.

  • One balance

    API calls and Chrome extension exports share the same credits, on the free plan too.

See plans and credit packsHow credits work

Facebook Ad Library Company Ads API: frequently asked questions

Send GET /v1/facebook/adlibrary/company/ads with either pageId or companyName and your key in the x-api-key header. Returns the ads one company or page is running in the Facebook Ad Library, each with its creative, status, spend, and targeting info.

Recipes that use this endpoint

More Facebook endpoints

All Facebook API endpoints